A method to organize information?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Paula Cristina Vaz wonders: <<Can you advise me a method to organize
information on a technical document? For example, if you want to build a
database, you talk to your users and make an ER diagram. Then, you build a
database from the ER diagram. Is there
a similar method to "compose" documents?>>

If you look at a broad collection of user manuals, you'll find that one
overall pattern is extremely common: a pattern that follows how users of the
product will approach the product. This approach must usually handle two
situations:

1. This is the first time the user has ever seen the product. In this case,
the user typically goes through the following steps:
- What is this thing that I'm being forced to use? Write an introduction to
explain what it is.
- Okay, so I now know what it is. What can I do with it, or what should I do
with it? Provide an overview of the types of functions the product can
perform and how they link together.
- Great! Suddenly I have all this creative potential, but with all these
options, where should I begin? Provide guidance on the types of tasks users
will typically perform, ideally in an order that links all the tasks
together. (E.g., If the user reads a word processor manual, they would
see--in order--the following steps: how to type, how to apply styles and
text formats, how to format pages, how to check spelling, and how to print
out the document. Plus many more, of course, but that's a simplified version
of the typical sequence.)

2. The user is coming back to the manual to learn how to use some aspect of
the product, or at least now understands what they can do with the product
and wants to actually do it. In this case, users typically go through the
following steps:
- I can't remember how to print. Where are the instructions on printing?
Provide a table of contents and an index that points to the instructions on
how to print. Use synonyms in the index, since users don't always choose the
same keywords you would choose.
- Okay, now I've found the right chapter. Now what do I do? Run through all
the options, in logical order. (e.g., pick a printer plus a paper size
that's available on that printer, make sure the current layout fits on that
paper, add page numbers, select which pages to print, and actually print the
document. Plus more, of course.)
- Great. I've printed the document, and it doesn't look right. Now what?
Provide troubleshooting information.
- Hallelujah! It finally looks right. What next? If there's a logical next
step (e.g., making a backup copy of the file), explain this.

<<Is there a way to find out if the document you just write is a good
document?>>

Testing documentation quality can get as complicated as you want it to get.
Most simply, hand the document to a few people who resemble the typical user
of your product (ideally, hand it to the actual users), and ask them to try
to use the product. If they can't accomplish something reasonably
efficiently using your documentation, you need to rewrite. If you want to be
more sophisticated, pick several people who represent different types of
user, and ask each one to accomplish a series of tasks. Monitor them closely
to see where they encounter problems, and consider presenting them with two
different types of documentation to see which one works best. (This is
called "usability testing", which is a whole profession distinct from
writing; usability tests can become remarkably sophisticated and complex if
you want to do them scientifically, but there's no real need to perform a
full PhD-level study in many cases. Look in the techwr-l archives on
raycomm.com to see what we've said on this subject over the past 10 years or
so--use the keywords "usability testing" and "quality"--and ask us again if
you have more specific questions.)

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

Tarzan's rule of data processing: Never let go of one vine until you have a
solid hold of the next.--Anon.
 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.