Inconsistent text style
Nobody has claimed this yet.
- 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
- Each sentence on its own line
- Line break at some character limit (80, 100, etc)
Referencing external RFCs
- [[RFC0000]], Section x.y: http://link.to.rfc
- Square bracket syntax links to bibliography at the bottom
- RFC0000, Section x.y
- Regular markdown link. Still included in bibliography at the bottom
Referencing fields
- Title case - Trace ID
- regular sentence case - trace ID
- inline code -
trace-id - link to heading Trace ID
- Possibly in combination with one of the other options like
trace-id
- Possibly in combination with one of the other options like
Others?
There may be other style inconsistencies I haven't noticed that others have. Please feel free to comment them
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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