University of Bath

Creating a Guide

How to create a basic or detailed Guide to help users achieve a task.

When to create a Guide

Create a Guide to:

  • provide information, advice or instruction to help someone complete a specific task
  • explain in plain English how the user can follow a policy

Don't create a Guide:

  • for content which is better provided by an external source (where the University isn’t the authoritative source of information)
  • as a policy guide which is the exact reproduction of the policy
  • to act as a Service Start page
  • as a last resort for content that doesn’t fit into other format types

Before you create a new piece of content, search the website to see if it already exists and talk to other people who could be responsible for it. We don't want to duplicate content on the website as this can be confusing for users.

Choosing the right Guide subtype

Once you've selected the Guide content type for your page you can choose to write a Basic Guide or a Detailed Guide.

Basic Guide

Use this for short, direct instructions on one topic or theme.

A Basic Guide only consists of one section. There will be one heading on the page below the title, and all the content for your guide will exist below that heading. You should use a Detailed Guide for anything more complex.

Detailed Guide 

If you need to create a Guide of two or more sections you should use a Detailed Guide.

Detailed Guides have in-page navigation that lets users skip from the top of the page to individual sections. The text you use for your section headers will also become links in the in-page navigation.

Once you've added your content to a section in the publishing platform, click 'Save' to open up a new section to fill out. Each section must focus on just one idea or part of the overall theme, with the whole Guide encompassing a single process. 

Naming your Guide

The title for your Guide should:

  • be easy to understand - use simple English and avoid using technical terms if possible
  • use active language rather than passive ('Applying for a scholarship', not 'Scholarship applications')
  • help users identify what action the content will help them complete - include a direct action so the user knows it will help them achieve their aim ('Secure a place through clearing and adjustment', not 'Clearing and adjustment process')
  • be clear who the content is for - place the Guide in context so the user recognises it as relevant to their need ('Types of placements for undergraduate students', not 'Placements')
  • be limited to 65 characters if possible so users can read it in entirety on search results

Your title shouldn't:

  • include the words 'guide' or 'guidance' (these are automatically displayed on the page)
  • be a question (use 'Apply for undergraduate accommodation', not 'Can I apply for accommodation?')
  • start with 'How to …' or 'Find out …' as this will produce cluttered URLs and search results
  • contain commas or dashes as this will create confusing URLs - use a colon instead if you need to separate phrases ('Tuition fees and charges for all students: 2014 to 2015')

Writing a Guide summary

Use the summary to explain what your Guide will help users do. Also say who will benefit from your Guide, for example:

Title: Suspending your studies or leaving the University
Summary: What you need to do to suspend your studies, the process for coming back to University, and what to do if you want to leave your course.

The summary should be no more than 160 characters.

Writing a summary for a specific audience

If your guide is for a specific audience (like postgraduate students or staff who are personal tutors), it's important to make clear who it's for in the summary. Some summaries may need to be more explicit than others, for example:

Title: Applying to university after a break in studying
Summary: If you are age 21 or over, you are defined as a mature student. Find out how to apply to an undergraduate course and the different routes into higher education.

This is especially important if you have separate content items which have a similar topic but different audiences, for example, one guide for how a pregnant student can get support and another for how staff should support them:

Title: Getting advice if you are pregnant while studying
Summary: How we can support you if you are student having a baby, or you have a young child.

This should not be confused with:

Title: Actions staff should take to support a pregnant student
Summary: What academic staff should do when they learn a student is pregnant, including how to assess need and make necessary adjustments.

In some cases, referring to your audience in the third person may be the clearest option. This is fine for the summary, as it can make search results more helpful, however you should avoid using the third person in the rest of the guide.

Writing Guide content

You should always try to address the reader directly ('you can apply for a parking permit') rather than writing about them in the third person ('staff can apply for a parking permit'). You will have made the role of the user clear in your title and summary, so they will already know whether the guide is for them or not.

If your Guide contains information that's only relevant to certain audiences, you can use headers to make the purpose of the content clear. See our formatting guide for how to create headings.

Things to remember when writing your Guide

Do:

  • write concise phrases ('Select the option', not 'You should select the option' or 'The student should select the option')
  • write in plain English to make your content as understandable as possible
  • structure your content so that the most important information is at the top
  • break content up into sections that are easy to read
  • use headings to structure the content and help users to navigate
  • consider breaking long sentences or paragraphs with a lot of information into bulleted lists
  • make sure your headings follow the same principles as when writing the title
  • make it absolutely clear when an action is required by the user ('You must contact Student Services' rather than 'Contact Student Services', 'You must complete a form' rather than 'Complete a form'

Don’t:

  • include technical terms in headings unless unavoidable - and then only if you’ve already explained them on the page
  • use generic or needless headings ('Further information' or 'Introduction') - users don’t want an introduction, they want the most important information
  • structure your content as FAQs - you won’t need them if your content is concise, well-structured and written in plain English

Resources to help you write your Guide

The University's style guide will help you make sure you're using the same terminology, style and tone as the rest of the website. This is important so that website users can understand us easily through the consistency of our content.

Our formatting guide will help you create appropriate headers, links, lists and other formatting for your page. This is important because it makes the information we provide clearer to website users.

If your guide will be a series of numbered instructions for users to complete in order, you'll need to read our guidance on How to Guides.

Adding a call to action

A call to action is the next thing you want the user to do after reading your content. The Content Publisher has special fields for entering a call to action.

Make sure your call to action:

  • is active ('Find out more about...', 'Contact the...', not 'More information is available…')
  • makes the destination of the link clear to the user
  • does not end in a full stop

Your call to action can be a link to a web page, an email address or a phone number.

If your content doesn't have a call to action, choose 'No call to action' and enter a good reason for not having one in the 'Reason for no call to action' box below.

You should always try to think of the next step for the user.

Adding responsible organisations and groups

After you have added all your content - including any images, media and contact details - you will able to select an owner or associated group for your page. This allocates permissions for who in the organisation is able to maintain the content.

A guide for adding responsible organisations and groups is available to help you do this.