University of Bath

Creating a 'How to' Guide

How to create a Guide to describe a step-by-step process or provide technical instructions for a user.

When to create a 'How to' Guide

Create a 'How to' Guide:

  • to outline a step-by-step process which the user has to follow in order to complete a task
  • to give the user technical instructions for using a piece of software or technology

Don't create a 'How to' Guide:

  • if you are listing information in no particular order which is better captured by a bulleted list

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 do not want to duplicate content on the website as this can be confusing for users.

For assistance in naming your 'How to' Guide, choosing the right Guide type, and writing your Guide summary, see Creating a Guide.

Writing your 'How to' Guide

When explaining a detailed process in which your user has to follow step-by-step instructions, it is important the structure and writing are clear and easy to follow.

Write directly to the user

Start each step with a verb where possible. This helps make your instructions clear and concise, and ensures you use an active voice, for example:

  1. Log in to Agresso using your username and password.
  2. Select 'Enter and Expense Claim (Staff)' or 'Enter and Expense Claim (Student)'.
  3. Enter your information into the form.

Use the word 'select' rather than 'click' for accessibility purposes and for mobile devices users who will not be using a mouse.

Use numbered lists

Identify the logical order in which the user needs to carry out the steps to complete the task, then present this as a numbered list.

Label different stages with headings

If the overall process has different stages, divide them into multiple sections with subheadings. See our formatting guide for how to create headings.

Do not number your subheadings or you might end up with nested numbered lists. If a process is split across various stages restart the number sequence after each subheading.

Using visual media

Use visual media, such as images and videos, to support your written content, not as a substitute for it. Also remember you must include detailed and meaningful titles and alt text with your images and videos, and that all videos should have subtitles available.

Things to remember when writing your 'How to' 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 steps in the order the user will need to complete them
  • break content up into headed sections, using numbered lists to structure the content
  • 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:

  • use visual media such as screenshots or videos without supplying the same information in written form for users with screenreaders
  • use icons (such as the Windows Explorer symbol) unless the context makes is clear for users with screenreaders what they have to select
  • use the greater than symbol > to direct the user to the next step
  • use generic headings ('Further information')
  • use needless headings ('Introduction' as 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 sequential order

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.

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.