Skip to content

Writing style

We come from different disciplines and levels of familiarity with Agile or technical subjects. Consider your audience when writing content, including how much or little they know about your topic. Writing in plain language with shorter, simpler words and bulleted lists instead of long sentences helps everyone. At the same time, be sure to use specific terms known to those in the same discipline.

Tone

Content appearing in the guidebook should be welcoming, personable, and free from jargon or acronyms.

Person

Write in second person as though you're speaking to the reader. Exceptions are made to this rule when a policy must refer to CivicActions team members in the third person.

How to capitalize titles and headings

We use sentence case for our titles and headings. When using sentence case, we capitalize the first word, all proper nouns, and a word following a colon. We do not capitalize the next word if a title or heading begins with a number.

Examples

  • Site building using Drupal
  • Engineer's role in client relationships
  • Accessibility: Everyone has a role

Automated suggestions for improvement

The GitHub Actions build outputs a list of suggestions to improve the readability, language, and grammar of the file(s) your pull requests touches. You are encouraged to review and use any suggestions that make the content easier to read and understand.

Specific terms

  • Specify Free/Libre Open Source Software, which can be shortened to FLOSS. Do not use just "open source software". See Richard Stallman's explanation if you want to know more.

This page was last updated on December 4, 2023.