Skip to main content

New manuals format

The information in this blogpost may now be out of date. See the current GOV.UK content and publishing guidance.

The Product Gaps team are building a new format for long, structured guidance. We’re calling this format ‘manuals’, because many of the things that will live in it define themselves as manuals, such as the Valuation Office Agency’s Rating Manual. (The word ‘manual’ won’t appear to users, though, as it wouldn’t make sense on some other documents eg the Civil Procedure Rules).

The most basic form of a manual will be ready for departments to start using in a few sprints’ time. Feedback is welcome!

How it works

Each manual has a contents page listing the sections of the manual. Section pages display all their sub-sections as headings that you can scan through and open out relevant sections in-page. For users who are thorough readers, not scanners, you can also ‘open all’.

Contents page
Contents page
Section page (open and closed headings)
Section page (on the right one heading is opened)

Criteria for using the manuals format

These are our draft criteria for using the manuals format. Please comment if you have a document you think would be a good fit for the manuals format, but which doesn’t meet the criteria.

A document can use the manual format if it fulfils all of the following criteria:

  • It requires at least two levels of hierarchy, ie it is broken down into sections and sub-sections
  • It is too long to be easily readable in an HTML publication or detailed guide
  • Its users think of it as a single body or document
  • It is a legal or guidance document

Findings from discovery

As part of the discovery for this format, we chose a few manuals and explored their user needs in more detail through analytics, surveys and existing research. Based on these user needs, we made and tested a number of prototypes. We learned some important things.

1. Reading long documents on the web is tricky. Lots of the documents on GOV.UK were paper books originally, but this doesn’t mean we should artificially retain the constraints of a book as some online services do. Until now we decided (like Wikipedia) that long HTML pages are best: people are comfortable with scrolling and it doesn’t create artificial breaks in the content, or the need for too many clicks. But for really long documents (the HMRC manual we’re currently working on has 3000 pages) and those that have a clear hierarchy, users found very long pages overwhelming. That’s why we’ve designed a format with collapsible sections.

2. Users like a beginning and an end. This might seem obvious, but if you’re creating a manual in a web-native way, you can structure it more like, well, a web. The service design manual was built like this: to browse through it, you choose your own adventure. However, this hasn’t tested well.

Where a manual is government guidance and possibly enforceable (eg the service design manual is the supporting document for the service standard which government digital services are required to meet), many users want to know they can read the whole of it, or a certain section, to do their ‘due diligence’ - and they feel worried or frustrated if it’s not clear how to do that.

3. Communicating the changes. It’s really important to users to know when something changes and what’s changed, and this is especially important in long guidance or legislative documents. We’re going to start by improving on our usual pattern for change notes on documents, but we know there’s a lot further we can go: eg allowing people to sign up for email alerts from a single manual, showing the changes in-line, like a diff, or having a ‘time-machine’ functionality so you can view a document as it was on a given date. But these things are some way off.

4. There’s still a need for documents offline. One of the first comments on the excellent HTML Government Digital Strategy was “where can I download the PDF”. Users of all kinds of manuals say the same. They want to read documents offline or print them, whether on an eReader or a laptop connected to the internet, and a PDF is generally the most familiar way to do that. For now we’ll be adding a button to print the page which will make it clear to users that you can print and in the future we’d like to auto-generate PDFs.

Keep in touch. Sign up to email updates from this blog, or follow Alice on Twitter.

Sharing and comments

Share this page


  1. Comment by Tim Blackwell posted on

    Hi. Do you have an approximate timetable for when DWP's advice for decision making and decision maker's guide are likely to transfer to these formats?

    • Replies to Tim Blackwell>

      Comment by Alice Newton posted on

      The format itself is now available in one of the GOV.UK publishing tools, but it is the responsibility of departments to create their content in it. Having looked at the document you mention, I agree it would be a good fit for the manuals format, and we will encourage DWP to migrate it.

  2. Comment by Alan posted on

    I like the look of this format as it has potential answers to questions that our customers are asking us about the length of HTML documents and whether they can easily be printed.

    In Home Office Science this would be a useful format for former statistical bulletins that have been transferred to the HTML format. For example Immigration Statistics

    and other statistics would benefit by not having to have two publications knitted together to appear as one.

  3. Comment by Andrew Robertson posted on

    Hi Alice
    Would you be able to do a new blog or update this with a few published examples when they are available on GOV.UK? Would be really useful too to hear an update of any customer feedback or analytics as the product is developed.

    A slight aside: Trying to enforce the writing style guide is that little bit more tricky when examples of new products like the screen shot here don't follow the guidelines. Specifically, date range should be '2014 to 2015' or more specific like 'April 2014 to March 2015' and title probably should be lower case?

    • Replies to Andrew Robertson>

      Comment by Alice Newton posted on

      Hi Andrew,

      As soon as the first manuals are live on GOV.UK, I will blog about it again with links to them.

      As for the screenshots, they don't reflect any published content on GOV.UK and in fact the content is drawn from a large range of sources and makes no sense together. We'll try to keep dummy content in any illustrations to style, but we prioritise communicating about changes quickly over perfecting the detail.


  4. Comment by Antony Hopker posted on

    We're really interested in this. We have a number of long-ish documents that we have mostly resisted putting into html guidance format.

    Examples: We had a go with this one, turning what was a 20 page guide and a 20 page FAQ into a single piece:

    And we've so far decided not to do it with this:

    Some questions occur:
    Will they be able to accommodate illustrations or detailed tables (for example a large thumbnail you could click to open in a new screen)?
    Would it be easy to transfer from an existing html guide into the new format, keeping the same slug etc?
    Can you do something with the printing so it picks up the Contents as well (this is the biggest thing holding us back)?
    Auto-generated pdfs sound great, but can they be clearly timestamped somehow so people know how old their own copy is? And would they generate page numbers?

    I'd be very happy to discuss this further with some of our other examples.

  5. Comment by Alison Morton posted on

    This looks like a big improvement on what we currently have. Any idea when it's likely to reach the HMRC VAT Guidance manuals (V series)?

    • Replies to Alison Morton>

      Comment by Alice Newton posted on

      I'm glad you think so, Alison. We're still working with the HMRC digital team on a date for transition, but HMRC will communicate it well in advance of it happening.

  6. Comment by Ingrid Morris posted on

    Hello Alice,

    Could you let me know your time frame? ie when/how will the new format be launched and available for wider family use?