The information in this blogpost may now be out of date. See the current GOV.UK content and publishing guidance.
Now that agencies and ALBs are beginning to create detailed guides, based on their validated user needs, we thought it would be useful to make it clear when and how you can use the format.
Please use the detailed guide format (example) for all web-based guidance for practitioner and professional audiences.
Note that guidance for mainstream audiences (citizens and any general audience) is created by GDS and then fact-checked by the agency or ALB.
Any guidance you currently publish in a file format (eg PDF factsheets or guides) should be created on GOV.UK using the 'publication' content type, sub-type 'guidance'(eg: www.gov.uk/government/publications/dbs-update-service-applicant-guide). There is no need to duplicate a publication with a separate detailed guide (but you can link to them from other detailed guides).
There are a few specific instances (exceptions) in which you would create an HTML publication of sub-type ‘guidance’. These are explained at the bottom.
Criteria for detailed guides
We’ve published a blogpost that explains the criteria for detailed guides. A detailed guide:
- usually answers a specific, task-orientated user need
- addresses professionals and practitioners
- is something government has a duty to provide
- is written and updated by agencies and departments themselves
We’ve broadened the criteria to include one more option:
- contains information that a user needs in order to understand and contextualise future tasks
If your content does not fit the criteria, you will find that it is most likely:
- a list or a directory (we are addressing this format need with a new format called ‘finder’)
- a policy paper or policy supporting detail
- a document collection
eg this is not guidance: https://www.gov.uk/government/publications/national-careers-service-the-right-advice-at-the-right-time
Browsing to and searching for detailed guides
Detailed guides have a prominent place in the GOV.UK architecture. Users will find they:
- show up in the specialist categories that are part of the mainstream structure of the site (eg: https://www.gov.uk/browse/justice/rights/policing) - the positioning of these categories will improve soon
- show in categories that will be listed on topic and organisation pages (you can add these to your pages if you have not already done so)
- return in the main GOV.UK search
- show up in collections
Length and style
We expect detailed guides to be no longer than they need to be. If guides are written to a single, clearly defined user need, they are likely to be quite short and succinct.
There is a whole section in the style guide that explains the tone and content of detailed guides. The most common problem is that the guide does not address the user need, or only starts to address it late on in the guide. Information about the history of the guidance, the reasons for it or the policy objectives, should not be included.
User needs
We are monitoring existing detailed guides to ensure they meet a user need and are written to GOV.UK style. Our audit of existing detailed guides identified those that did not fit the format: editors should have removed these and redirected to the content in the correct format. We’ll be checking this shortly. There is also an audit of quality which is underway.
You’ll need to enter the user need for each new guide as you create it (or when you re-save an existing guide).
Editors from agencies that have created user needs during user needs workshops will be able to enter their validated user needs when creating detailed guides. Editors in departments will have to enter a user need when they create a detailed guide, and these, too, will need to be validated in due course.
Publications, sub-type ‘guidance’
If you have an existing manual or handbook that you distribute, or guidance that you issue in a published form (as hard copy), you need to create a publication of sub-type guidance.
eg: https://www.gov.uk/government/publications/state-aid-a-beginners-guide-guidance-notes
Some agencies publish the majority of their guidance in PDF format. You may wish to keep this approach as it is what your users prefer, or you may want to move to a web-based approach (ie detailed guides) where you can update the content more dynamically (without the need to reissue a new version of the PDF). Speak to your transition manager if you want to know more about these options.
HTML publications
HTML publications are presented on GOV.UK just like other publications (PDFs, Word documents etc) except they are created in HTML.
You can use the HTML publication option to publish an e-book in place of a printed manual, or an HTML version of PDF content such as a factsheet or leaflet. First, create a publication page and then add the attachment as an HTML publication.
Your HTML publication will have a publication date and sometimes a reference number or ISBN number. You shouldn’t update it in the same way as you would update web-based guidance, because it will need to be re-issued as a new, dated version.
Example: https://www.gov.uk/government/publications/small-business-commitment
Your format decisions
The reason we have several options is that these different approaches suit different organisations for different reasons. If you have any questions about the format that would best suit your guidance, please get in touch with GDS through your transition manager or the support form you will find on your Publisher dashboard.
8 comments
Comment by Suzanne Amos posted on
Thanks for the blog post - and I look forward to future posts. But do you think it's right to let government agencies continue churning out PDFs? You write: "Some agencies publish the majority of their guidance in PDF format. You may wish to keep this approach as it is what your users prefer…"
Allowing government agencies to produce pdfs will surely allow them to carry along the same old route of writing 'everything you ever wanted to know about topic X' rather than focusing tightly on user needs 'As a small business, I need to do X'.
Comment by lizhitchcock posted on
Hi Suzanne
All government departments and agencies should become 'digital by default' ensuring they won't continue to produce information in a way that's not easily searchable/findable by users. However, for transition, we need to be able to accommodate existing processes as we try to improve them.
We also need to keep in mind the end need of the user. For some specialist users, the ability to have (for example) a long report as a PDF will be exactly the right option, as they will want to print it. We look to agencies and departments to continue their research with users to keep on top of how they want content presented.
In the future we want to develop HTML and detailed guide functionality so that these can be downloaded as PDFs. This will allow users to produce an offline version of content if that’s what they want.
Comment by Suzanne Amos posted on
Thanks, Liz.
Can I ask another question? It's about the content type 'guidance'?
I'm working on guidance for a government agency, which, in the past would produce 100-page PDFs telling you ‘everything that government thinks you should know about a certain topic’.
As far as I can tell, guidance is usually information for a professional audience, fleshing out regulations that are unclear - so guidance tells you what you need to do to comply with the law and helps you carry out a certain task.
Re-reading the style guide, there's a section called 'Content types', and within that, a section called 'Publication types'. It mentions a publication type called 'guidance’ and it implies that it's OK to produce guidance as a fully-fledged publication.
But at my agency we’re trying to steer clear of this, as we want to start with a blank sheet of paper, work out user needs - and then write concise guidance as a detailed guide format that meets user needs.
There's also a section in the style guide called 'Writing for GOV.UK' and within that a section called 'Publishing legal and technical content', which says: "If you have to publish legal jargon, it will be a publication ..." So it's OK to cordon off information that contains legalese - and hide it in a publication.
From the outside looking in to GOV.UK it feels confusing. Especially as, when communicating with policy teams and subject matter experts, I'm trying to give a clear message that all guidance on GOV.UK needs to start from a user need and be in clear English.
If GOV.UK allows guidance to be in the form ‘Publication’ I think that will give out the wrong message. In my experience, publications are huge things with a cover sheet, an intro with shedloads of background and history – and then on page 50 you get to the meat.
Grateful if you or colleagues could clarify 😉
Comment by Andrew Robertson posted on
Hi Liz, if there is some flexibility for organisations to use a PDF/HTML 'publication' or a web based 'detailed guide', how does that help users who are searching for 'stuff' in the publications filter at http://www.gov.uk/government/publications?
Should detailed guides be added as a document type, or merged under the existing 'guidance' option, otherwise if we shift from the traditional way of creating PDF files (or new HTML equivalent) to create web 'detailed guides' [which I think is a sensible move] is there a chance our customers won't find them?
For example http://www.gov.uk/animal-welfare says it is 'guidance' but it's not in the publications section of GOV.UK under 'guidance' as it is a detailed guide rather than a publication type of guidance. Yet http://www.gov.uk/government/publications/farm-fires-protecting-farm-animal-welfare is also about animal welfare and is in the publications filter. Is there a risk customers will see some stuff but not others, simply because of the format we have chosen?
Comment by lizhitchcock posted on
Absolutely correct: our intention is to include detailed guides under the 'publications, guidance' filter, however it’s not going to happen immediately because of other priorities related to the transition of agencies and arm's-length bodies.
Comment by Andrew Robertson posted on
Brilliant, thanks for clarifying Liz. It's cleared up a lot of confusion with me and colleagues here!
Comment by Suzanne Amos posted on
Liz, very sorry to bombard - if you're at SPRINTGO next week maybe we could grab a coffee? .... Above in your blog post it says: 'We expect detailed guides to be no longer than they need to be.' Would you say 8 pages of A4 is too long? I've divided up the guidance (detailed guide format) into 9 H2 headings, with loads of H3 headings underneath the H2s. I guess you'd say 'It depends. Wait until it's in the Publisher - and see if people can navigate it OK'
Comment by Louise Stone posted on
Hi Suzanne,
Just to come back to you on your point about the section in the style guide [There's also a section in the style guide called 'Writing for GOV.UK' and within that a section called 'Publishing legal and technical content', which says: "If you have to publish legal jargon, it will be a publication …" So it's OK to cordon off information that contains legalese – and hide it in a publication.]
That's not what we intended to be inferred here. We're not promoting publications as somewhere to hide legalese, rather we're assuming that if you're putting content that you're not writing to style onto GOV.UK, it's because it already exists as a (probably offline) publication.
Where you are, as you say here, starting with a blank sheet of paper to work out user needs and then writing concise guidance to meet them, this should take the form of a detailed guide - ie web-original content. Ideally, all guidance would be written like this, with a clear user need in mind.
We know there are instances, however, where organisations need to provide an online version of existing guidance in exactly the same format as has already been provided elsewhere. We need to provide a way for organisations to do this and that's the intention of the 'guidance' subtype within publications. As (hopefully) more people move to digital by default and towards the idea of starting with a user need, rather than a piece of content they want to 'put on the website', there should be fewer guidance publications and more web-original guides.
One more point - about whether 8 pages of A4 is too long - you're right to assume that 'it depends'. We want the user's need to be answered - and only the user's need. If there's a single, discrete need that requires 8 pages (to take someone through a complex, but unified process, for example, that they would be expected to complete in one go) then I think the argument's there to be made that it's necessary.
However, I think any piece of content that is that length will and should alert whoever is proofreading or 2i-ing it that it needs thoroughly questioning to make sure it really does answer a user need and doesn't combine several needs into one piece. User testing, even as you're writing, can help you to see if it works. Cath's recent post on getting insights in under a week could really help in these situations.