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.