Writing security.gov.uk documentation

The first step when writing your document - or updating an existing one - is to ask the question “What does the audience need?”

It may sound obvious, but in reality a lot of content is written with the intention of including as much information as possible, making it long and difficult to digest.

Your aim should be to write as clearly and concisely as possible. Therefore you should take the time to make a note of who your audience is and the context they operate in.

Also, take care to use the language of your audience. If you are in any doubt as to whether they will understand a particular term or phrase, try to use a more accessible equivalent.

The next step is to think about what you want to happen; that is, what is the document for? When someone reads it, what do you want them to understand? What should they do after reading it?

By considering the actions and behaviours you want the audience to adopt, you can work out the essential information you need to convey.

To help you write more concisely, try to keep your sentences short. 25 words or fewer is a good guideline, but don’t try to write up to 25 words every time.

Following on from that, try to keep your paragraphs short as well. This is especially useful for policy documents, where capturing one policy requirement per paragraph makes it easier to quote or cross-reference specific requirements.

The first time you use an acronym in a document it’s good practice to spell it out, providing the acronym afterwards. For example:

This policy applies to all government departments and their arm’s length bodies (ALBs).

There are some exceptions:

If you feel that you can make a convincing argument that the acronym is commonly known, you do not need to spell it out - for example “MP” or “NHS”

In headings use the spelled-out version without providing the acronym as well - or use the acronym alone if it is commonly known and you need to keep the heading short

Note: Using a phrase that is normally an acronym in a heading does not count as first use in that document.

Although Latin abbreviations are common in academic and legal contexts, they are not as easy to read as the plain English equivalents. They are also often confused with one another and used incorrectly.

Instead of the most commonly known abbreviations, use the following phrases:

• “for example” instead of e.g.
• “that is” instead of i.e.
• “and so on” instead of etc.

Title case - where every word in a sentence or phrase is capitalised - has a negative impact on readability. Only capitalise words in a heading if they explicitly require it; that is, if you would normally capitalise it in a sentence.

Overuse of bold text also affects readability. Try to only use it to emphasise key words that the reader must make note of. For example, when introducing a list of mandatory policy requirements you could apply bold formatting as follows:

Government organisations and their ALBs shall:

Note: The GDS style guide and GOV.UK design system do not currently agree on this. I have taken the advice from the design system, as it seems both more up-to-date and in line with our requirements for security content.

Left-aligned text is easier to read. Fully justified text - that is, aligned on both the left and right margins - creates wider spacing between words. This causes problems for people with dyslexia or similar challenges.

Bullet lists are used for points of information that do not have to be presented in a specific order.

When writing a bullet list, you should normally:

• introduce the list with a lead-in phrase ending with a colon, as above
• ensure each bullet makes sense when read with the lead-in phrase
• begin the first word of each bullet with a lower-case letter, unless it’s a word that would normally be capitalised
• keep to one sentence per bullet, using commas or dashes to break up the sentence if required

Also, you should not:

• punctuate the end of each bullet with a semicolon or full stop
• use a bullet list to list the steps of a process - use numbered lists instead
• add “and” or “or” to the end of the penultimate bullet
• create a bullet list with only one item

Note: Sometimes you can introduce a bullet list without a lead-in phrase that follows directly into the text in each bullet. For such a list you can begin each bullet with a capital letter, but note that the other rules should still apply. For example:

We have considered the following key indicators of compromise in mobile devices:

- Device state - locked or unlocked
- Configuration
- Compliance with policy and process
- Events, including user activity and connections to systems 
- Third-party apps, especially restricted apps

The GDS style guide is an alphabetised resource of style, formatting, and vocabulary guidance. Note that the search feature does not work properly. Instead, you should use Ctrl+F (Windows) or Cmd+F (Mac) to search the guide.

The Typography section of the GOV.UK design system contains useful information on font, heading, and paragraph formatting.

The Foundations of Writing in Government: JASPER training course gives a useful overview of how to write clearly and concisely.