Re: Write the User Guide First

Subject: Re: Write the User Guide First
From: Tim Altom <taltom -at- IQUEST -dot- NET>
Date: Sat, 9 May 1998 07:54:04 -0500

>About ten years ago I took a company sponsored human interface design
>course a few years ago from an outfit called the Learning Tree or some
>such thing. They guy giving the course was an ex-NASA type -- who, btw,
>had some great war stories about the early days of the space program. One
>of the first things he told his audience, exactly one of whom was a
>technical writer, was that when designing a system that humans will use,
>write the user guide first.
>It made sense to me (as the sole tech writer), nor did it seem to be a
>particularly radical idea, but the project managers, analysts and
>programmers also taking the course were scandalized. How could you write
>the user guide before you built the system?
I've heard this before. It's essentially the same point as "Write
requirements first". Or, to be even more succinct, figure out the interface
before you bother with the function. I saw an example of this on a client
site where enterprise software, developed over many months, was unveiled for
company executives at a test site, where the company's foremost expert in
the interface was to give a demonstration. The windows, however, were so
dense and the functionality so dispersed that he stumbled during the demo,
forgetting where to access certain functions. And he'd lived with the
software 10 hours a day for many, many weeks. To the client's immense
credit, he learned from this module and started the next module with a
requirements document culled from user and tester feedback and wishes.

Many e-types are scandalized by this, because they put most of their dollars
and emphasis on functionality. These types are often identifiable by their
statement that "If they can't figure out how to run this thing, then maybe
they shouldn't be hired." And, true, if the product doesn't perform, then
all the lovely interfacing won't make a bean's worth of difference. All this
says is that both are extremely important and shouldn't be discounted. Our
problem as a profession is that we're almost always called in after the
requirements phase is done, if there's such a phase at all.

I'm a big fan of the "write the doc first" approach, but I've rarely seen it

Tim Altom
Simply Written, Inc.
Creators of the Clustar Method for task-based documentation

Previous by Author: Re: "Engineer"
Next by Author: Taking notes and other drudgery
Previous by Thread: Re: Write the User Guide First
Next by Thread: Re: Write the User Guide First

What this post helpful? Share it with friends and colleagues:

Sponsored Ads