WritersUA 2011 Monday – Hotrodding your online help
This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Hotrod My Help” presented by Leah Guren. If you find any inaccuracies, they’ll be mine.
Leah’s presentation style is both informal and professional. She started out by introducing herself as “this deranged woman”. She then became more serious quite quickly. Her talk was about design of online help systems. She used the metaphor of hot rodding – talking about the paint rather than what’s underneath.
Introducing the topic
Leah’s talk was entirely tool agnostic, and described techniques that we can apply to our documents with very little effort.
Nevertheless, Leah pointed out, this stuff matters for a number of reasons:
- Design should match the subject matter.
- Better design improves usability.
- We’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.
- When people see help with a sloppy design, they’re less likely to trust the information.
- Design should support the meaning of the content.
- It should make it easier for people to find what they’re looking for, to recognise it and to use it.
Leah also pointed out that if your readers are noticing the design, then you have made a mistake. (As a side note, I tweeted this point and received an interesting reply from Bill Kerschbaum.)
The design concepts
Leah introduced us to some design concepts, the jargon. Mastering the terminology lets you defend you choices with more authority.
Leah introduced us to the acronym PARCH:
- Proximity – When elements are close together, we recognise that they are related.
- Alignment – Choose where you position elements on the screen, to develop a meaningful design.
- Repetition – Repeated visual patterns help people to access and remember the information efficiently.
- Hierarchies and dependencies
One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.
Use alignment for a less sloppy design.
Consider things like colours, icons, placement. Stylistic repetition reinforces the information for the user and gives them more confidence.
We need contrast so that people can see the differences in meaning between different elements on the page. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.
This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.
Other concepts and techniques
- White space – Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.
- Plumb lines – Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.
- Indents and text wrap – Indents help the concept of contrast. Good examples are bulleted lists.
- Paragraphs – Leah recommends the following design techniques for paragraphs, to enhance readability:
- Flush left, ragged right.
- Single line spacing.
- White space between paragraphs.
- Chunking – Use white space intelligently, to show the logical visual chunks of information.
- Nesting – Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting. The rule in technical communication (a tacit contract with the user) is this: if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.
Examples – applying the concepts
After introducing all the theory, Leah moved on to examples of web page makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.
These are some of the mistakes she fixed up:
- Messy text.
- Dashboard that was not designed to be meaningful.
- Screenshots taken without care and without tidying up afterwards.
- Sloppy text wrap, that probably happened when pasting content from elsewhere.
- Inconsistency in capitalisation, punctuation, and so on.
- Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
- No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
- Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
- Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
- Use of blue (usually used to denote hyperlinks) as an emphasis or point colour.
- Too many layers of hierarchy (too much nesting) in a table of contents.
- Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
- Empty topics.
Help authoring tools
If the problem we’re addressing lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.
Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.
Thank you for a lively session, Leah!
Posted on 15 March 2011, in online help, technical writing, WritersUA and tagged online help, technical communication, technical documentation, technical writing, user assistance, WritersUA. Bookmark the permalink. 3 Comments.