w3c / w3c/trace-context

Inconsistent text style

Open
#485 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Editorial
Dominant language
Python
Stars
510
Forks
80
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the specifications in this repository alongside the referenced baggage work, starting with the inconsistencies listed for line breaks, RFC references, and field names. Done means the project has agreed on preferred text conventions and a clear plan for applying them globally to the specifications.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.