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.
  • Contrast
  • Hierarchies and dependencies

Proximity

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.

Alignment

Use alignment for a less sloppy design.

Repetition

Consider things like colours, icons, placement.  Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast

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.

Hierarchy

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.

My conclusions

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!

Hotrod My Help
=============
Leah Guren (Cow TC) 

http://www.cowtc.com/

Leah started out by introducing herself as “this deranged woman”. Herpresentation style is informal and easy. She then got more serious quite quickly. She does many presentations about tehcnical communication. Today she will talk a lot about deisng. Use the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Everything she will talk about is tool agnostic. These are techniques that you can apply to your documents with very little effort.

This stuff matters because the design should match the sujbect 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.

If your readers are noticing the design, then you have made a mistake.

Good design follows a series of rules.
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 introduced us to some design concepts – the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to a new acronym: PARCH:
* Proximity – When things are close together, we recognise that they are related.
* Alignment – Choose intential places to position elements on the screen, to develop a meaningful design.
* Repetition — Repeated visual patterns help people to access and remember the information efficiently.
* Contrast
* Hierarchies and dependencies

Proximity:
==========
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.

Alignment
=========
Less sloppy design.

Repetition
==========
Consider things like colours, icons, placement.

Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast
========
We need contrast so that people can see the differences. 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.

Hierarchy
===========
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:
==============
* 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, show that we’re showing logical visual chunks of information.

* Nesting — Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting, which all of us do. The rule in technical communication (a tacit contract with the user): 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
========

With the theory out of the way, Leah moved on to examples of 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.

Some of the mistakes she fixed up were:
* 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 (link colour) as a highlight 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 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.

My conclusions
==============

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!

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 March 2011, in online help, technical writing, WritersUA and tagged , , , , , . Bookmark the permalink. 3 Comments.

  1. Another great read. Leah is from Israel – as am I btw!!

  2. Sarah, thanks for sharing these notes. I’ve been starting to dig a bit more deeply into design theory and this was a great, quick read. Is there a link to the presentation or anything?

  3. Hallo Mumpy and Bill

    Thank you both for dropping by :) and for your nice words. Bill, the presentations are online but visible only to conference attendees. Maybe Leah will publish it on the Cow TC website later? I’ll try to bump into her again while I’m at the conference and suggest it to her.

    Cheers, Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,396 other followers

%d bloggers like this: