Writing style guidance

(Work in progress - needs nicer formatting too)

For each piece of guidance, give:

• A statement of the guidance.

• The reason(s) why (so that authors can learn and use their judgement about it).

• One or two examples from the published guides of how to do it right.

• One or two examples of how not to do it.

Conciseness

Edit. Edit. Edit. Whatever you write first will always include redundant words, sentences, or even paragraphs. So edit it down.

Why?

• A long guide is off-putting to even the most eager reader.

• You’re wasting the user’s time if they’re reading words that don’t add to their understanding. They’re here to learn, not to read your prose.

(needs examples of sentences or paragraphs re-written to be more concise)

Explain concepts clearly (but concisely)

Explain any concepts that are the target audience (specific to the guide) is unlikely to understand already. This is one of the hardest parts. After you’ve removed all the redundant words, consider whether anything actually needs explaining more.

(needs why and examples)

Tense

Use the present tense almost all the time (including describing the functioning of some code when it’s compiled, even though it’s not strictly compiled yet). Only use the future tense when something is literally in the future when reading the guide.

Why?

The future tense (in English, at least) makes for clumsy, cluttered sentences ("When you click the button, the UI will turn green." means the same as "When you click the button, the UI turns green." but using more words). More importantly, it can make more complex sentences harder to read and understand.

Example:

• Yes: The test class uses the properties to get the application details

• No: The test class will use the properties to get the application details

• Yes: You will learn how to build and test a simple REST service.

Voice (active vs passive)

Write in an 'active voice'. Don’t write like you were taught to write science reports at school.

Why?

Passive sentences are often harder to read and understand. They’re also often longer (see 'Conciseness').

Example:

• Yes: implement the @GET annotated methods:

• No: The @GET annotated methods are implemented in the following code:

(needs better examples)

Pronouns

Avoid using 'we' and 'I' in guides. Use 'you' when necessary but don’t overdo it.

Why?

It’s generally not clear who 'we' and 'I' are. In a blog post, which is more personal, it’s clear who the author is. Even though we’re writing the guides to be more conversational than normal doc, 'we' and 'I' often isn’t necessary. Also, sentences with 'we' and 'I' in them tend to be a bit longer and don’t say as much (see 'Conciseness').

Examples:

• Yes: The fastest way to work through this guide is to clone the git repository and use the starting project that is provided in the start directory.

• No: We have provided some files for you to make this tutorial easier to consume so clone the git repository and…​

(needs better examples)

Contractions

Use common contractions (e.g. it’s) but don’t use weird, clumsy ones (e.g. wouldn’t’ve).

Why?

It makes the writing more conversational and less dry. "Let’s" can make the text more sympathetic but use it sparingly because it could just be patronising if used a lot.

Examples:

(need examples)