mdn / mdn/browser-compat-data

Document style for notes

Open
#6,229 0 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs:guidelines idle
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.