Skip to content

Latest commit

 

History

History
80 lines (58 loc) · 3.03 KB

writing-style-guide.md

File metadata and controls

80 lines (58 loc) · 3.03 KB
Raw

Technical writing style guide

General notes

Ensure simplicity, accuracy, and accessibility. Aim for a broad understanding, even for select audiences. Be concise – readers are busy; avoid unnecessary words.

Style principles

Language

  • Use American English: -ize rather than -ise endings, ‘color’ instead of ‘colour’
  • Avoid slang words
  • Use gender-inclusive pronouns – they/their/them
  • Active voice, avoid passive.

Abbreviations and acronyms

  • No full stops in abbreviations: eg, ie, PhD, etc, v (note, not vs), plc, Inc
  • Write acronyms as said (eg, radar, laser, captcha), use initial caps for entities, avoid capitalization
  • Minimize the use of acronyms and initialisms. Spell out on first use, eg peer-to-peer (P2P)
  • Refer to the Cambridge dictionary.

Legal and investment

  • Avoid investment or legal advice.

Punctuation

  • Use the Oxford/serial comma
  • Use single quote marks: 'cascading disruption'
  • Use en dash – (option-hyphen on a Mac keyboard; Alt-hyphen on PC)
  • Use a full stop at the end of the last bullet point.

Capitalization

  • Lowercase for job titles, degree names, and university departments
  • Use lowercase after a colon, eg 'Feature: this feature is about...'
  • Book, film, and game titles should be in italics, and academic papers should be in 'single quotes' – avoid subtitles.

Numbers and time

  • Spell out one to nine: one, two, three, four, five, once I caught a fish alive, except for percentages: 1%, 2%, 3%
  • Use numerals for anything higher: 10, 11, 12, 13, 14, 15
  • Spell out million, billion when in prose: there are nine million bicycles in Beijing
  • Use abbreviations for money: £5m, $10bn, 12tn yen
  • When talking generally, use MMMM DD, YYYY format, eg February 1, 2018
  • For technical purposes, use ISO 8601 standard for dates and time: YYYY-MM-DD eg 2018-02-01.

Bullet lists

  • Start with a capital letter and use full stops in complete sentences. You can format the bullet 'title' in bold if there is one:
    • Feature name 1. This full sentence describes the feature in more detail.
    • Feature name 2. This full sentence describes the second feature in more detail.
  • Omit full stops in short itemized lists; use it after the last bullet point. For example, the discussed feature includes such items as:
    • Item 1
    • Item 2
    • Item 3.
  • In shorter statements, full stops can also be omitted. For example:
    • Maintain uniformity across all documentation
    • Encourage user interaction with clear instructions
    • Incorporate visuals judiciously to enhance understanding.

Links

  • Write clear and meaningful links; don’t use 'here' as a link. Always embed links; don’t just paste one as is.

Headlines and titles

  • Headlines are 'Sentence case only'. The limited use of capitals is a way of avoiding confusion for proper names. Use initial caps for navigation section names and topic headings.
  • No full stops at the end of headlines, pull quotes, captions, and other display matter, or when referencing figures: just 'See Figure 1 for details...'.