The information in this blogpost may now be out of date. See the current GOV.UK content and publishing guidance.
A detailed guide should provide guidance for professional or specialist users to complete a particular task.
To write a detailed guide, you should always start with the user need. Pasting this temporarily into the top of your document will help shape the content around the need. What do you want people to know or be able to do? Have this in mind as you write and it will keep the guide tightly focused.
All content on the page should be there only if it is directly related to this specific need. Anything else should be cut.
Make sure you know from your content plan what other closely related user needs are being covered elsewhere. This gives you an overview of the whole area and prevents guides overlapping with each other and duplicating content. This will make it easier for users to pick out from search results the specific guide that they need for their task.
Start the guidance with the most important point. Don’t contextualise or introduce a broader topic, or explain why a piece of guidance, or a strategy or a policy exists - get to the main point straight away. The reason the user is on the page should be clear from its title, so you shouldn’t need to reorientate them.
You can cover more general points later in the text (if they’re still relevant to the specific user need). A lot of users will only read the first few words to confirm whether they’ve got to the right place. On average, readers will read only 20-28% of a web page.
As per the style guide for all of GOV.UK, sentences should be short and in plain English. Essential technical or specialist terms can be used, but you should explain them the first time they appear in the guide.
Keep the content active - this means the subject of the sentence will be at the beginning (passive sentences have the object at the beginning).
For example:
Active - ‘You should draw up safety policies and procedures for staff’
Passive - ‘Safety policies and procedures should be drawn up for staff’
It’s also important to keep subheadings focused on an action. Users often scan down the page, using these to pick the section they want to read. Make sure each one highlights what the user can do or find out in that section.
For example:
Active - Apply for a licence
Passive - Licence applications
The subheadings should logically break up the content into clear sections by which the user can ‘navigate’ through the text.
Make sure you cover all the acceptance criteria for the specific user need - or that you reallocate acceptance criteria to other user needs if you discover while writing that they fit more logically elsewhere.
You don’t need to include legislative details. Where a task has to be completed in line with legislation, you can mention this and link to it on legislation.gov.uk but you don’t need to go into detail.
2 comments
Comment by Andrew Robertson posted on
It would be *really* good if you can provide examples of effective detailed guides that are live on GOV.UK, perhaps with brief explanation why it is so good. Alice Newton did this for collections and that was very helpful (https://insidegovuk.blog.gov.uk/2014/01/27/are-collections-better-than-series/#comments).
I've looked at published examples of detailed guides (and other content for that matter) but it can be confusing when they seem to contradict the style guide.
Comment by David Potts posted on
I've recently started to write detailed guides for HMRC as content transitions to GOV.UK.
One question - is it acceptable to include worked exampled (of, for example, a tax calculation) in a detailed or specialist guide? From the customer's point of view it can make it easier to understand what is being said if they can see an example of it in practice.
David