Style guide for software development standards

This guide tells you how to write and format standards and other documents for this repository.

We want our standards to be:

clear
consistent
easy to read

If a standard is easy to understand, it's also easier to follow it correctly.

Be clear and focused

A standard should set clear rules. A guide should give clear advice.

Be concise. Focus on what is most important. Avoid woolly language and excessive detail.

It should be straightforward to answer "Does this project meet the standard?" with a "yes" or "no". Basically, in developer terms, a standard should be easily testable.

Be easy to skim

We'd love everyone to read every last word of these standards. But in reality, people often skim the content they read on the web.

To make content easier to skim:

use short sentences and paragraphs
break up writing into multiple sections with clear subheadings
display information in bulleted lists
put the most important information first

This helps users to quickly understand the main points of a standard. It also makes it easier to find the specific information they're looking for.

Use plain English

Our guides and standards should use plain English whenever possible. What we write about can be complex, but the way we write about it doesn't have to be.

We are writing for a specialist audience. But even specialists want content to be easy to read:

when given a choice, 80% of people preferred sentences written in clear English ... the more specialist their knowledge, the greater their preference for plain English

It's fine to use technical terminology, but avoid corporate jargon.

Check your writing for clarity

Hemingway is an online tool that helps make writing easier to read.

It makes suggestions for when to simplify vocabulary or split up sentences that are too long.

You don't have to obey every suggestion from Hemingway, but it can be a useful guide.

Use Markdown for formatting

There are a few variations of Markdown, so we use the standard GitHub syntax.

Read GitHub's formatting guidance

Name each file using snake case (for example, style_guide_for_standards.md).