Page tree
Skip to end of metadata
Go to start of metadata

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.


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.


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.


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, 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.

  • No labels


  1. Unknown User (jpo23)

    Just thinking about how-to content, would it be useful to have an approximate 'time to complete task' in the introduction? This might help people decide whether it's something they want to do now, over lunch, over night.

  2. Unknown User (pgw22)

    The line-height on the list-items makes a world of difference!

    When setting things up with GitHub they use JavaScript to detect your OS and present you with the most relevant information up front but also lists the other options underneath the page heading (


    1. Unknown User (if243)

      That sounds like a good way of doing it. There is actually an OS-detecting script on the BUCS site already but I think it's only used on this page:

      1. Unknown User (jpo23)

        Sounds good, but I'd like to discuss this kind of thing further. I'd want to examine the user journey to this kind of content. Example: I want to set up email on my IOS device. Could well be that I'm looking this info up on a Uni PC in the library and then doing the necessary on my IOS device in front of me.  In this case, I want IOS info, but the PC is serving me up Windows content. Know what I mean?

        1. Unknown User (pgw22)

          Agreed, which is why the other options are also available, listed before the content of the page. Anyway, it was just another example alongside accordion and tabs. Right now I don't have any strong inclination for this rather anything else.

  3. Unknown User (rf396)

    Looking through I think you've made a number of improvements. Particularly in terms of the language used.

    Thinking forward to review by CS...

    I think that the absence of screengrabs may be viewed as a loss - perhaps in the long term the written instruction can be supplemented by a gallery for each OS/device or videos, though of course the risk is that they age.

    Some of the text size and line-heights on some pages and (particularly) lists makes legibility a bit of a challenge that maybe can't be addressed now in the context of V3 but you should be prepared to acknowledge and explain this.

    The pink link colour is a bugbear. Any chance of changing this to a standard blue in these prototypes?