Journals by RSS
Journals by EmailThis post is part of a series on usability and maintainability. At first, meeting the needs of content consumers through usability can seem at odds with meeting needs of technical communicators through maintainability. My purpose in these posts is to discuss how technical communication best practices can satisfy both needs. I’ll use Gurak and Lannon’s usability criteria of users being able to “find what they need, understand the language, follow the instructions, and read the graphics” (A Concise Guide to Technical Communication, 31).
What about instructions can stop people from following them? This is a question about the structure of the instructions themselves, separate from the language you use, which was the previous subject in this series.
Structure of Instructions
The main obstacle I’ve heard when asking this is when instructions are too long and complicated. I’m sure we’ve all seen—and perhaps even written at some point—steps in a process that ended up turning into fat paragraphs. Or a set of instructions has twenty or thirty steps.
The rule I was taught in college was not to exceed six lines in any paragraph. I admit that I have broken that rule because I have written material where it didn’t make sense to me to break the paragraph at six lines. However, the theory behind the rule is that people get lost in dense text and also lose a sense of progression. (Charles Dickens would not have made it as a technical writer.)
As soon as someone sees a process hitting steps in the teens, they’ll start wondering how long this process is and start flipping to the end. We tend to freak out a little if we see instructions that get too far into double digits because it’s an indication that we’re doing a task that’s long, drawn out, and complicated.
What do you do when you have a lot of material to regurgitate on the user? Use short paragraphs and more headings. Break long procedures into smaller sets of instructions. I’d rather be led through a process with three main tasks of ten steps each than one long process of thirty steps.
Writing short paragraphs with more headings and fewer steps simplifies maintenance because it’s easier to find information that needs to change. Say I have that thirty-step procedure broken into the three tasks with ten steps each. If I need to change a couple of the steps in the last third of the procedure, I know to look in the third task and have only ten steps to look through rather than having to wade through thirty steps to find the right place to make the changes. The additional headings help me locate the information I need to change.
Visual Layout
SImple page or topic layouts benefit users by helping them stay focused in the content and not become lost. I admit that sometimes I have an urge to become artistic in laying things out so that the appearance is engaging. However, there is the danger to be overly artistic. Too many sidebars or note boxes can confuse users about what they are supposed to read or look at next. I think of websites with so many ads that I lose track of where the content is that I’m reading. Users may give up on the instructions because they’re not visually laid out simply enough.
A simple layout also aids maintenance because adding information requires less manipulation. A note box may look just right with a certain amount of text in it, but as soon as you add two sentences, the resulting change in box size could throw off the layout and require extra time to make things look good again.
It also helps in localization situations because the same concept in different languages can take up different amounts of space. If the layout is simple enough, it can adjust fluidly to different lengths of text without a lot of manipulation by the writer to get it to fit.
On that subject, layout is a greater issue with print media, which even in our electronic deliverables has a place in PDF documents. Web documents can run on forever if needed, so they need less maintenance in that sense. Documents designed for printing require more consideration on layout than Web documents. But having a simple layout can still save the writer maintenance time and money.
Previous: Usability and Maintainability: Understandable Information
Related entries (auto-generated):
Usability and Maintainability Not So Incompatible
Usability and Maintainability: Understandable Information
Usability and Maintainability: Navigable Information
3 Comments to 'Usability and Maintainability: Instructions They Can Follow'
January 15, 2009
“What do you do when you have a lot of material to regurgitate on the user? Use short paragraphs and more headings. Break long procedures into smaller sets of instructions. I’d rather be led through a process with three main tasks of ten steps each than one long process of thirty steps.”
Sometimes, you cannot divide one long procedure into many smaller procedures. For example, one software product contained an installation wizard that had 14 screens. A user had to do all 14 steps in sequence, or abandon the installation. Each screen needed an explanation. There was no way that I could divide the procedure into smaller procedures.
[Reply]
January 15, 2009
I suppose what I said came across sounding like hard and fast rules! Even if they were rules, you’ve reminded me that there are always exceptions. Every situation deserves its own consideration for what’s best. So you’re absolutely right: There are situations where it’s not possible to break things up. I even said myself that sometimes I purposely don’t break up a bulky paragraph because it just doesn’t make sense to. However, I think a fourteen-step procedure isn’t too bad.
Let me give an example of what kind of long procedures I’m talking about, though. In one project, we have a feature where the user can create an Excel file of data and then use the spreadsheet as a source for mail merge output in Word. That could have been one extremely long procedure to slog through if I did it as one process. But I broke it up into three tasks: (1) setting up a document to reuse so that the user wouldn’t have to do it from scratch every time; (2) generating the Excel document in our application; and (3) using the spreadsheet to create the specific output from the reusable document or template. (Fortunately, this process was redesigned and is being developed so that it is much simpler and contained entirely within our application.)
It’s possible that when something takes twenty-five or thirty steps to document, maybe the design needs to be looked at to see if it can be simplified somehow.
[Reply]
January 16, 2009
Ben, thank you for clarifying.
“When something takes twenty-five or thirty steps to document, maybe the design needs to be looked at to see if it can be simplified somehow.”
Yes, I agree.
[Reply]
Set Me Straight. Leave a Comment.