Creating a guide

You should use the guide content type if you need to:

• explain the steps someone should follow to use a University service
• explain how to follow a University policy or procedure 

Don’t use the guide content type if you need to:

• publish policy or compliance type content (use Corporate information)
• explain how to attend an event (use Event)

Don’t create a guide for:

• content that only exists to link to a page outside of the University website
• content that duplicates other content on the University website
• content that is already provided in more detail or with greater authority by another organisation or website
• creating content which is primarily a list of things (including links)
• FAQs (these lead to unfocused, poorly structured content that risks duplicating content elsewhere)

Creating guide content

The following stages occur over a series of workshops held on Teams or in-person. 

1. Define the problem 

During this stage, Web Services will work with you to understand the problem you are trying to solve. The output of this stage should be a user story where we establish the user need for the content. We write user stories in the format:

As a… [the type of user/role] 
I want… [the goal] 
So I…[the reason/benefit of the content] 

An example of a user story would be: 

As a…current student 
I want…to find out how to login to my email account 
So I…can contact a member of staff

A user story serves as a reminder of the content’s purpose when we’re creating it. It also helps us test the content with users. User stories work best when they relate to a single topic or task and lead to something actionable.

Generally speaking, try to keep a guide focused on a single user story.  If you do decide to have more than one user story on a page then make sure that the content relating to the most important user story comes first on the page. Also keep in mind that if we add multiple user stories then the content can become dense and harder to scan.  

2. Understand the topic  

This phase is about gathering a foundation of evidence about the guide topic that can be used to inform and shape the content for your guide. This might include:

• subject matter experts interviews
• business data
• customer feedback
• market research
• website analytics

The output of this stage should be a report produced by Web Services which summarises the findings and evidence. 

3. Understand the user 

When looking to understand users, ask these questions: 

• What do our users know about us?
• What do we know about their needs? 
• What do we know about their mental models? 
• What are their main tasks? 
• How do they carry out those tasks? 
• What are their main frustrations? 

Build up a picture of the user and their journey not just on the website but across all touch-points they might have with the University. Ideally you would do this through different types of evidence:

• Qualitative evidence (e.g. user interviews).
• Quantitative evidence (e.g. website analytics).

4. Create the content 

Content sketching 

The initial stages of creating content should be a collaborative process. This allows us to use the skills and knowledge across the project team and make everyone accountable for the content that is produced.  

The project team will meet in a workshop to do this. In this session, a member of Web Services will present the information and findings gathered so far and remind everyone of the user need(s).  

There will then be an exercise where each person is asked to quickly sketch the content of the guide. You don’t need to provide too much detail, it can be headings or scribbles to illustrate ideas and concepts. Each person will present their sketch and ask for feedback. The purpose of this exercise is to explore different ideas and reach agreement on the content structure.  

Content drafting 

Once you have a content structure you can then proceed to writing a first draft of the content.  

One way of approaching this is through pair writing. This involves writing the content alongside another member of the project team in real time. Pair writing can be useful as it helps you work faster and fosters trust through collaboration.  

Even if you don't decide to write the content through pair writing, the editor who writes the first draft should ask for feedback when it's ready. When giving feedback on a draft, you should: 

• Be helpful – tell people what can be improved and what's working well. 
• Be clear – give examples and ideas to help with improvements. 
• Be kind – remember that a lot of work has gone into the content. 

Do:

• use clear, straightforward language
• aim for a score of 9 or better on the Automated readability index
• use Hemingway App to help improve content readability
• structure the page based on the information needs of the user with the most important content at the top
• break the content up with headings to make it easier to scan
• use short, concise sentences like 'Log in with your short username' rather than 'Students should login with their short username'
• use information panels to highlight vital information
• include a call to action if appropriate 
• include contact details for enquiries
• follow the guidelines outlined in the University content style guide 

Don’t:

• repeat the summary
• add walls of text which make the content difficult to read and scan
• use long sentences
• add videos and screen shots without adding the equivalent content as text
• use unnecessary headings such as 'Introduction'
• structure headings as questions (this front-loads headings with similar phrases like 'Can I...', 'What happens if...', 'I am...' and makes the content harder to scan

Writing a guide title

Guide titles should:

• be informative and give the reader a sense of what the content is about
• make sense out of context, this helps the reader understand the content when it’s presented in search engine results
• where possible be active, for example, 'Access student software from home' not 'Home studying and using student software'

Do:

• use sentence case in the title (this means you only capitalise the first letter of the first word unless a word is a proper noun or formal title)
• use colons as a separator, for example, 'Postgraduate research essentials: starting your research degree' 
• provide the full context for the guide, for example, 'Using face coverings on campus’ not ‘Face coverings'

Don’t:

• use a question as a title

Writing a guide summary

Use the summary to explain the purpose of the guide and identify who it is for.

Aim for a sentence, however if that’s difficult then two sentences are ok. The summary is the first sentence of the content so should make sense when it's read continuously with the rest of the content. Using phrases like 'Learn how…' and 'Find out how…' in the summary is fine.

Resources for writing guide content

The University content style guide helps editors achieve consistency across all our content.

Guides ownership 

To ensure content accuracy and relevancy, all guides should have a named content owner. This is usually the member of staff who works with Web Services to create the content for the guide in the first instance. Where a guide relates to more than one University service or department, two content owners are permitted. 

Content maintenance and archiving

It’s important to ensure the ongoing accuracy, relevancy and quality of guides. To do this, Web Services will conduct regular audits of guides on the website to check the standard of content.

As parts of these checks, Web Services will contact content owners and ask if the content is still needed and, if so, up to date and accurate. If a content owner does not respond to confirm then Web Services reserve the right to archive the page and remove it from the website. 

If a guide is archived then it will remain in an archived state for 12 months after which time it will be permanently deleted. 

There might be occasions when a guide presents an immediate risk in terms on providing inaccurate or misleading information to users. In this situation, Web Services reserve the right to remove the page before confirming with the content owner.