Index & minimalism, concluded

[Karin Warren <warrenk -at- JACOBS -dot- CSOS -dot- ORST -dot- EDU>]

This concludes the two-thread message I sent a few weeks ago regarding
an electronic index of articles for issues of Tech. Communication, and
minimal manuals.

I tried several Internet sites to search for the index (thanks to those
who helped me with this!) but gave up because I couldn't get the info
downloaded. (I'm new to Internet, so it may've been my problem.) I
didn't check out STC's BBS because of the long-distance cost involved.

I do plan to check a few other sources, including some libraries, and
--here's the good news--if I'm successful in finding an index of articles
for TC in electronic form, I'll be happy to e-mail the list to anyone
interested. I'll keep you informed...

----------

Thanks also to all of you who so generously supplied the minimal manual
references. I have more than enough material to keep me reading all
summer!

----------

Regarding the latest thread on feature- to process-oriented documentation
(what I term a program-oriented Reference Guide and a task-oriented User's
Guide, respectively), I'm all for Faith's common-sense approach: finding out
what the users are doing with the system and writing the manual accordingly.

Although some info will be left out, i.e., some of the advanced features
of which the programmers are especially fond, the User's Guide will at least
allow the users to be productive. (This, by the way, relates to minimalist-
style documentation, where info is purposely excluded to (1) reduce the
size of the document and thereby reduce the intimidation factor, and (2)
to encourage users to explore on their own.)

In an ideal world, the advanced and extra features, error messages, etc.
could be placed in a Reference Guide. But I have yet to find a client who
wants two manuals for a given software program.

My way around this is to create a User's Guide -- short, limited in scope
but with real-life examples that take users from the beginning to the end
of a task, and with a few good screen captures interspersed in the text.
Then I create Quick Reference cards or sheets that can be propped up by the
user's terminal. These include numbered steps for basic tasks (without the
details), tables of keystrokes, commands, etc., some of which weren't
mentioned in the User's Guide. Items in the Quick Reference refer to page
numbers in the User's Guide, when appropriate.

It's not a perfect system, but it seems to work. In one instance, support
calls were reduced by 80 percent.

Karin Warren
Keyword Writing & Editing
warrenk -at- jacobs -dot- csos -dot- orst -dot- edu