Document style for notes
Nobody has claimed this yet.
- Dominant language
- JSON
- Stars
- 5.8k
- Forks
- 2.6k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 186
Description
There are certain aspects of notes that we can't lint for. We ought to document a lightweight style guide for writing notes. We could probably start by codifying a few common practices:
- Use the present tense (the inspiration for this issue, #6228, plus a few others like #2151 and #505)
- Use browser names and avoid engine names where possible (e.g., "Chrome" not "Chromium", "Firefox" not "Gecko")
- When a note applies only to some subset of versions of a support statement, then begin the note with the limitation (e.g., "Before X", "After Y", "From Z to W")
- Avoid imprecision by specifying versions, not dates or times (e.g., avoid "now", "currently")
There are probably others I'm missing.
We could probably write up the guide and illustrate with a few bad/better/best examples.
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
No files or tests are named. Start by reviewing the cited issues #6228, #2151, and #505, then inspect existing notes and documentation conventions in the repository. Done means a documented note style guide with a few bad, better, and best examples, covering the listed practices and any additional patterns found.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100