Skip to content

Latest commit

 

History

History
32 lines (30 loc) · 1.86 KB

STYLE_GUIDE.md

File metadata and controls

32 lines (30 loc) · 1.86 KB

Documentation style guide

This contains Kriti's notes from when she was revising docs in June 2023. This will eventually be a style guide.

  • Use sentence case for titles. Don't capitalize random nouns.
    • Good:
      • Connect a database server
    • Bad:
      • Connect a Database Server
      • Connect a Database server
      • CONNECT A DATABASE SERVER
  • When referencing external services or software, refer to them how they refer to themselves. e.g. write "Let's Encrypt", not "lets encrypt"
  • When linking to external sites, identify the site. e.g. don't say "Django settings", say "Django settings (see Django docs)".
    • We don't want to send users to external websites unexpectedly – external links should be clearly identified.
  • Every item in a single list should be the same type of thing.
    • Good list:
      • Apples
      • Oranges
      • Bananas
    • Bad list:
      • Apples
      • Apples are grown all over the world
      • You can buy apples at the grocery store
  • If you are using lists to collect different types of facts together, then give each list item a title, e.g.
    • Apples
      • Origin: Apples are grown all over the world = Where to buy: You can buy apples at the grocery store
  • Don't have bullets on the same line as an info-box. It's okay to have an infobox under a list item, but it should be part of a previous bullet, not have its own bullet.
  • Generally aim for simpler language since it's more accessible to non-native speakers. e.g. "acquisition" is more succinct, but "where to buy" is simpler.
    • Where to buy: You can buy apples at the grocery store
    • Acquisition: You can buy apples at the grocery store
  • Don't use short-forms e.g. say "distributions", not "distros"