w3c/trace-context

Inconsistent text style

dyladan opened this issue · 2 comments

dyladan commented

While making changes on both this repo and on baggage, I noticed that our text style is quite inconsistent. I would like to try to make some decisions on our preferred style so we can apply it globally to our specifications.

Line breaks

  1. Each sentence on its own line
  2. Line break at some character limit (80, 100, etc)

Referencing external RFCs

  1. [[RFC0000]], Section x.y: http://link.to.rfc
    • Square bracket syntax links to bibliography at the bottom
  2. RFC0000, Section x.y
    • Regular markdown link. Still included in bibliography at the bottom

Referencing fields

  1. Title case - Trace ID
  2. regular sentence case - trace ID
  3. inline code - trace-id
  4. link to heading Trace ID
    • Possibly in combination with one of the other options like trace-id

Others?

There may be other style inconsistencies I haven't noticed that others have. Please feel free to comment them

dyladan commented

Personally I would vote for:

Line Breaks

Each sentence on its own line. This allows for pull request reviews to make suggestions to individual sentences which is a natural unit of language without changing the line breaks for unrelated lines.

This is a full sentence.
This is another full sentence, which is much longer but still continues to be on the same line.
Reviewing a pull request with this style seems much easier in my opinion.
Very long lines can still be soft-wrapped by an editor if the reader wishes.

Referencing external RFCs

I personally like the regular markdown link syntax. The linked RFC is still included in the bibliography and it reads more naturally to me. It is much easier to link RFC0000 Section x.y than to read a full URL and linking only to the bibliography is annoying for the user who clicks the link to go to the section referenced.

Referencing fields

I like to use the inline code with markdown link like trace-id, but this is probably the most inconsistent aspect of our specification.

dyladan commented

Created a PR for a style guide with the above suggestions https://github.com/w3c/distributed-tracing-wg/pull/49/files