Re: "They don't need no stinkin' documentation..."

[Sandy Harris <sandy -at- storm -dot- ca>]

Andrew Plato wrote:
> 
> "Bruce Byfield" wrote...
> 
> > As for priorities, I think I'll evoke the Universal Panacea for this
> > list: it depends on the audience. ...
> 
> Yeah, but the "it depends" argument falls off at a base level. If you
> don't have your content ducks in a row, it doesn't matter if you're
> documenting pulsars for Stephen Hawking or Pokemon diapers for illiterate
> crackheads. The part that truly matters is the information. Everything
> else is dressing. It might be important dressing - but it can never
> overtake the value of the information.

Granted, the first requirement is to know what you're talking about. If
you don't have that, you cannot document well for any audience.

However, given that, I think you're looking at three essentials for what
you actually put in the docs -- technical accuracy, suitability for the
audience and decent organisation. Miss any of the three and you've blown 
it, usually fatally.

Technical accuracy I won't argue. We need it, period. One nice thing is
that it is moderately easy to check in most organisations. If you can
get your developers (SMEs, whatever) to review docs at all, and keep
them focused on content, they can help a lot here.

Audience analysis is also vital. For experienced system admins, I can
just say "set up a non-routable subnet on eth0". That's a perfectly
adequate description of a task they can do in their sleep. For another
audience, you'd need pages of explanation, procedures, examples, ...

You cannot even evaluate whether your doc is complete without some 
fairly clear notion of the audience.

Note that developers often cannot help much here. Marketing or tech
support or quality control may.

Finally, there's organisation. As I see it, this is where most of us
give most of our "value added". A document could contain all the
right information, at the right level for the audience, but still be
almost entirely useless if it is hard to read and harder to find
things in.

A lot of this is global stuff. How do I structure the document?
How do I handle basic information many readers will already
know, but that needs to be there for some? A glossary? Side text
boxes? Footnotes? References to other sources? Web links?

A lot of it, though, is low-level detail. 

  Do I explain this with an example? An analogy? An exposition of
  the theory behind it? Several of those?

  Which terms need to be in the index? How about synonyms for this
  audience?

  Is this clearer as a paragraph of text? A list? A table?

  What combinations of fonts, indentation and perhaps header/footer
  usage makes my headings easily searched?

I agree that obsessing about things on that level without first
getting the really crucial stuff right is fatal.

However, I cannot agree that content == crucial stuff. Methinks
matching the audience and overall organisation are also vital.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.  
For details and online registration, visit http://ieeepcs.org/2001

  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.