Creating a guide

Guide content type 

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

• provide instructional, task based content 
• explain how 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 an 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 lists of links
• FAQs (these lead to unfocused, poorly structured content that risks duplicating content elsewhere)

User stories

The starting point for creating a guide is normally a user story where we define the audience need for the content. We will then try to validate these stories with real users. An example of this would be:

As a…prospective student

I want…to find out how expensive it is to live in Dundee

So I…can budget appropriately

A user story serves as reminder of the purpose of the content when we write it and a way to measure its effectiveness once published.

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
• use titles that begin with 'How to...' or 'Find out...' as this create guides with similar titles and URLs

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.

Writing guide content

Do:

• use clear, straightforward language
• 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 the content is task focused
• 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 generic headings such as 'Further information'
• 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 call to action

Consider the next steps that the user should take after reading the content and, if appropriate, add a call to action. This can be a website address or an email.

Do:

• use active voice for the call to action text, for example, 'Book an appointment with Counselling' rather 'Counselling appointment bookings'
• use sentence case

Don’t:

• use a long sentence as a call to action
• add a full stop at the end of the call to action

Taxonomies for guide content

We use taxonomies in content types to organise content, publish it to different locations, and give it meaning so people can find it easily. Taxonomies take the form of assignable categories or tags.  

Below are the guide taxonomies that an editor should use.

Group

'Group' allows the editor to indicate the part of the University that is responsible for the guide. This taxonomy is also used to display guides in other areas of the website.

Guide category

The guide category taxonomy assigns one or more broad categories to the content so that it can be displayed on other areas of the website such as landing pages. Assigning a category also creates a link at the bottom of the content so the reader can view all pages that are associated with a category.

Resources for writing guide content

The University content style guide provides guidance for editors to ensure consistency of style across all University of Dundee content. It includes information about:

• Content principles
• Voice and tone
• Writing guidelines
• Reference manual for Grammar, spelling, formatting and University of Dundee terminology