How-to guides

What other sites are doing

I looked at other sites to see how they handle how-to guides and troubleshooting information.

Microsoft's support pages

Numbering instructions

For complex tasks, or problems where there's more than one solution, Microsoft uses splits up the pages with numbered headers.

Within the headers, instructions are given as an ordered list.

Explaining UI interactions

Things people have to interact with, like menus or button names, are given a special class - "ui" - which gives makes them bold.

Screenshots are sometimes used to illustrate what the user might see, but usually not to indicate specific actions.

Guides that deal with multiple problems

If a page has multiple problems with specific solutions, they are sometimes given as a table

Example: Installing the latest Windows 8.1 Update

Additional information

Some guides provide "before you begin" information about what users will need to know or have ready - this comes as an unordered list.

Additional information outside the main instructions is provided in grey boxes.

Example: How do I install or uninstall Internet Explorer 9?

Adobe's support pages

Combining multiple issues

Adobe tends to group their support how-tos on long pages organised by topic, rather than splitting them into separate pages. These pages can be read entirely or navigated with anchor links.

Example: Bullets and numbering

This style works better for introductory guides to a programme, rather than answering specific user problems. If a user finds the page by searching for a specific issue which is located midway down a long page, they still have some additional navigating to do before they can find the answer to that question. I don't think this is something we should imitate on our site.

Images

Adobe uses images in two ways:

• screenshots, which illustrate what the user sees

• UI icons, which indicate how the user should interact with the application.

The UI icons are inline and have no alt text, which presents accessibility issues.

Example: Thread text frames

What we can take from this

Styles for UI elements and user input

Following Microsoft's lead, I've created two new span classes, one for UI text and one for text the user should enter. They're in a css file in my sandbox folder.

The way these classes are styled is purely provisional, but I think it's a useful way to indicate different kinds of text without tying them down to specific styles.

Ordered lists for instructions

Ordered lists, rather than bulleted lists, help users to keep track of where they are in the guide and the order in which they need to complete certain tasks.

I do think we should use list tags for these sorts of guides, but they could really do with some different styling. Currently the small text and lack of spacing between items makes them difficult to read, especially with longer guides.

What I prototyped

Using email on iOS devices

This is one of the more popular guides on the site. It had 9,701 pageviews last year and people spent an average of 5 minutes reading it.

We should clarify which version of iOS the instructions were written for in case there are any changes to the OS.

Images

Ideally, our instructions should be clear enough that users can follow them without the aid of images, as not all users will be able to view them.

We should decide on a standard format for displaying images in instructions, particularly if we're highlighting certain parts of the image.

The images should also use alt text which is descriptive, rather than just the file name.

In this instance, I left the images out as they only showed iOS on an iPad, while our site's users are significantly more likely to be on their mobile phone than a tablet. If possible, we should try to use images which are relevant to all devices so that users don't dismiss them as irrelevant.

Styling

I tried using different styling on the first ordered list to make it more readable - the text is larger and there are margins between list items.

I think this is more readable than the standard formatting of the second list but it would benefit from some more work. Deciding on a consistent how-to format is something which will affect the rest of bath.ac.uk, and it's likely that designer resource would be required.

Setting up VPNs

The list of VPN guides was the 7th most visited in the last year, with 18,461 pageviews.

I created prototypes of two different guides for two purposes: Windows 7 for content and writing, and OS X for presentation.

Windows 7 - rewriting the copy

I use Windows 7, so it was easy to follow the instructions and adjust the copy without damaging the accuracy. I made some changes for fluidity of language and added full stops to fit with the style guide.

I used "select" over "click", as we can't assume a user is using a mouse - they may be using a keyboard, voice recognition software or another device.

OS X - examining the styling

Instructions were available for two different versions of OS X. As a user will only need to see one set of instructions, this was a good test subject for investigating how much information the users actually needed to see.

I tried using an accordion to display one version at a time. Tabs may be an alternative.

The left margins (or lack thereof) of the ordered list don't play well with the accordion, so this may need some additional styling.

Both versions are quite old so I didn't rewrite the instructions extensively, as they will likely need to be updated.