browser-compat-data icon indicating copy to clipboard operation
browser-compat-data copied to clipboard

Document style for notes

Open ddbeck opened this issue 5 years ago • 0 comments

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.

ddbeck avatar Jun 01 '20 18:06 ddbeck