Skip to main content

This is a new service – your feedback will help us to improve it.

  1. Guidance
  2. Writing Security Documentation

Writing documentation

We are working towards the launch of the beta version of the site. This site will host content created by the Government Security Group (GSG) and the Government Security Centres (GSeCs).

If you write security content - policies, standards, guidance, and so on - you can prepare for the coming changes by following the advice we have prepared here. It is not a comprehensive style guide, but it should help you when you write or revise your documents.

Note that this advice is based on existing government standards and ways of working. We hope you find it helpful!

Address your audience

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.

Consider your needs

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.

Keep sentences short

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.

Keep paragraphs short too

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.

Spell out acronyms on first use

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.

Avoid Latin abbreviations

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.
Use sentence case for your headings

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.

Use bold text sparingly

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.

Always left align your text

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.

Writing bullet lists

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.

Any questions?

To talk about the content in this article drop me an email at

For questions about the beta project get in touch with Angela Fisher