Standard content types

Detailed guides

When to use this content type

Use detailed guides to tell users the steps they need to take to complete a clearly defined task, like applying for a grant.

Use this type for content that is regularly updated, for example if the process to apply for a grant will change regularly. If it’s updated rarely, use a guidance publication instead.

Content containing background information about why a user needs to complete a task or the history behind it should be in a policy paper publication.

To work on a detailed guide, you’ll need a Signon account with access to Whitehall Publisher.

Create a draft

If you’re creating a new detailed guide

1. Go to Whitehall Publisher.
2. Select the ‘New document’ tab.
3. Select ‘Detailed guide’ and then select the ‘Next’ button.
4. Add the title, summary and body. Read the tone of voice guidance and formatting guidance for help.
5. Tick the UK nations where the content applies under ‘Excluded nations (required)’. If your content does not apply to a nation, you can optionally provide a link to alternative content for users in that nation.
6. Select ‘Limit access’ under ‘Settings’ if your draft is sensitive. This means only users from organisations tagged to the content can see it before it’s published. It will not be copied across to Integration.
7. Select the ‘Save’ button at the bottom of the page.

After saving the page, you can add attachments and images.

If you’re updating an existing detailed guide

1. Go to Whitehall Publisher.
2. Select the ‘Documents’ tab.
3. Search for the detailed guide you want to edit, and select the ‘View’ link next to it. This will take you to the edition summary page. If you only want to update the topic tags and nothing else, select ‘Change tags’ under ‘Topic taxonomy tags’. Otherwise, keep following these steps.
4. Select the ‘Create new edition’ button. If a new edition has already been created, select the ‘Go to draft’ link. You can then select ‘Edit draft’ or, if you do not want to use this draft, select ‘Delete draft’ and then select ‘Create new edition’.
5. Make any changes to the title, summary or body as needed. Read the tone of voice guidance and formatting guidance for help.
6. Do not change anything under the ‘Political’ heading. This is related to history mode and it will only need to be changed if your organisation is asked to take part in an audit of content before a general election.
7. Change the options under ‘Excluded nations (required)’ if needed.
8. Select ‘Limit access’ under ‘Settings’ if your draft is sensitive. This means only users from organisations tagged to the content can see it before it’s published. It will not be copied across to Integration.
9. Decide whether you need to write public change notes. Go to the bottom of the page and select the relevant option under ‘Do users have to know the content has changed?’, and add your change notes if needed (you can edit them again before you publish the draft).
10. Select the ‘Save’ button at the bottom of the page.

You can now edit the attachments and images.

If you select ‘Create new edition’ and you get a message telling you that the ‘document is in history mode’, you cannot update it without help from the Government Digital Service (GDS). See the guidance on removing history mode for more details.

Add or edit attachments

Make sure you correctly format attachments before you upload them.

Select the ‘Attachments’ tab at the top of the page. You can add, edit or delete attachments from here.

You can quickly overwrite previous versions of attachments if you upload new files with the same file names as your old ones.

You cannot add HTML attachments to this content type.

If you’re adding new attachments

When you add attachments:

• use the official title of the document
• do not tick ‘Attachment is accessible’ – this means users can ask for the attachment in an accessible format like audio or Braille

For each attachment, you get 2 codes that you can add to the body. You can either add the attachment as:

• an ‘inline’ link – this means you can add a download link to the middle of a sentence or in a bullet point list
• a ‘publication box’ – this means you will have a separate section with a download link, alongside information about how to request the attachment in an accessible format

Read the formatting guidance for more information about the different types of attachment code and when they should be used.

Add or remove images

Make sure you’ve correctly formatted the images before you add them.

Select the ‘Images’ tab at the top of the page. You can upload images here. Each image will need a different file name.

Once you upload an image, you’ll be given a ‘Markdown code’. You can copy and paste that into the body and the image will appear there.

If you want to remove an image, you can remove its code from the body. You can then upload a new version of the image and use its code instead.

Add or remove contact details

You can add contact details using your organisation’s contact directory. That means if the details in the directory are updated, they’ll automatically update in your content too.

Your organisation’s most used contact details should be in the contact directory. Find out how to create or update contacts.

To add a contact from a directory:

1. Go to ‘More’ at the top of Whitehall Publisher.
2. Select ‘Organisations’ and find the organisation that owns the contact. Select ‘View’ next to their name.
3. Go to the ‘Contacts’ tab and copy the relevant ‘Markdown code’.
4. Paste the code into your document.

You can remove the contact details by deleting the code.

If you do not want to use the contact directory, use the formatting guidance to add contact details.

Change the ‘first published date’

You can change the first published date if the same content was available on another webpage before, like on another GOV.UK page you’re unpublishing or a campaign site you’re closing.

Under ‘First published date’, tick the ‘This document has previously been published on another website’ box. Select the new date.

The new date will show when you publish the draft.

Add or remove tags to related mainstream content

You can tag the detailed guide to 2 pieces of mainstream content.

Mainstream content will:

• not have ‘government’, ‘guidance’ or ‘find-licences’ in its URL
• not be part of a specialist finder, like any of the content in ‘Air Accidents Investigation Branch reports’

Add the full URLs under ‘Related mainstream content’.

If it’s mainstream content with multiple chapters, you can only link to the first chapter.

Add or remove tags to organisations and events

You can tag your content under the ‘Associations’ heading. You do this by adding or removing associations.

These associations include:

• topical events – use this if you want the content to appear on a topical event page
• lead and supporting organisations – your own organisation will be set as a lead organisation as default, but you can change that or add any other organisations if they’re responsible for the content

Update settings of the draft

Under the ‘Settings’ heading, you can:

• change the ‘Email address for ordering attachment files in an accessible format’
• select ‘Schedule publication’, if you want the draft published at a certain time and date
• select ‘Review date’, if you want to get an email asking you to check the content at a later date after you’ve published it

Add or remove topic tags

You need to tag your draft to at least one topic page before you can publish it.

Your content will appear on the tagged topic pages when:

• the draft is published, if it’s new content
• you save the new tagged topic pages, if you’re updating existing content

See the ‘Education, training and skills’ topic page for an example of what these topic pages look like.

To add tags:

1. Select ‘Save and go to document summary’ on your current draft.
2. Under the ‘Topic taxonomy tags’ heading, select ‘Add tags’ or ‘Change tags’.
3. Tick the boxes next to each topic that applies. The arrows next to each topic will expand the topic out, showing all sub-topics in that topic ‘tree’.
4. Select ‘Save’.

To remove tags, select ‘Remove topic’ next to the one you want to remove and then select ‘Save’.

Choose topic tags:

• based only on what the content is about
• from anywhere in the topic ‘tree’, not just the areas that your organisation uses the most

Try to choose the most specific topics you can.

You can tag your content to as many topic pages as are relevant. There’s no limit.

Add or edit translations

Add a new translation

Read the guidance about deciding whether to add a translation.

If you do want to add a translation:

1. Select ‘Save and go to document summary’ on your current draft.
2. Under the ‘Translations’ heading, select ‘Add translation’.
3. Add the translated title, summary and body.
4. Select ‘Save’.
5. If you want to add any translated attachments, go back to the English version and add the attachments there. You can then copy the code and paste it into the translated version.
6. Check the translations are working by selecting ‘Preview translated pages’ under the ‘Preview’ heading.

If you’re adding a translation for a language that is written from right to left, there’s a different way to format links.

Edit an existing translation

If you want to update the title, summary or body of a translation:

1. Select ‘Save and go to document summary’ on your current draft.
2. Under the ‘Translations’ heading, select ‘Edit’ next to the relevant translation.
3. Make the changes and select ‘Save’.

If you want to update an attachment:

1. Go to the ‘Attachments’ tab at the top of the draft of the English version.
2. Select ‘Edit attachment’ under the relevant attachment.

Update the URL

URLs are automatically created from the page title when you first publish the content. You might want to update the URL if there’s a spelling mistake or if it no longer reflects the content.

If the content has never been published before

You can update the draft title and the URL will change.

If the content has been published already

You can:

1. Create a new piece of content with the desired title and URL.
2. Copy over the current content to this new draft.
3. Publish the new draft.
4. Unpublish the page with the incorrect URL. When you unpublish it, you’ll be able to set up a redirect to the new page.

The change notes history will be lost if you do this. If you need to keep that history, contact the Government Digital Service (GDS) and ask them to change the URL instead.

Publish the draft

Find out how to send the draft for review.

If you need to publish it urgently without a review, find out when you can publish your own draft.