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

Subject: "They don't need no stinkin' documentation..."
From: Michele Marques <MarquesM -at- autros -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 31 Oct 2001 12:50:13 -0500

Bruce writes (in defense of doc design):
> However, if you're writing for more casual users, then design
> could be the difference between them reading the
> documentation and walking away from all your hard work. It
> doesn't matter how good your content is if people can't or
> won't use it.

But if the content is wrong, or leaves out important points so that the
reader can easily get the wrong impression or do dangerous things, then
having your document easy-to-use doesn't matter. It just means people will
find the wrong information faster, or will be more likely to use your docs
to get the wrong impression.

I do agree, however, that there is a point to design. And it is a strawman
to determine whether you should spend 100% effort on content vs 100% effort
on design.

It is more useful to ask at what point do you have enough accurate content
that you should spend some time on design.

For example, if you have 80% of the content written accurately, it might be
time to apply some basic design principles. Until you have all the content
in place, you shouldn't be spending lots of time on layout. But if you have
a document (perhaps you inherited lots of content) that has no headings, no
table of contents, and all procedural instructions are in long paragraphs
(that could be broken up into numbered steps), it might be time to make a
quick formatting pass and generating a table of contents.

If the design is so bad that only the truly desperate will read
documentation (and then only when Support is unavailable), then the last 20%
of content (assuming it is the least necessary 20%) might not be worth
making that 80% slightly easier to access.

If the design is really bad (as implied by Andrew's formula of "good content
+ bad design = marginal doc"), you could turn this into an adequate
document. A good document would have all the content in place and, perhaps,
further improved design. An excellent document would have great content and
great design.

- Michele
Michele Marques, Technical Communicator
AUTROS Healthcare Solutions, Inc.
marquesm -at- autros -dot- com <mailto:marquesm -at- autros -dot- com>

This material is intended for the use of the individual
to whom it is addressed and may contain information that
is privileged, proprietary, confidential and exempt from
disclosure. If you are not the intended recipient or the
person responsible for delivering the material to the
intended recipient, you are notified that dissemination,
distribution or copying of this communication is strictly
If you have received this communication in error,
please contact the sender immediately via e-mail and destroy this message

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.

Previous by Author: RE: Alternative style for long, form-based procedures?
Next by Author: RE: Technical Writing Union
Previous by Thread: RE: "They don't need no stinkin' documentation..."
Next by Thread: Re: "They don't need no stinkin' documentation..."

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

Sponsored Ads

Sponsored Ads