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

["Dick Margulis " <margulis -at- mail -dot- fiam -dot- net>]

Michele Marques wrote:


>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 don't recall _anyone_ arguing to the contrary. That's why I called this a strawman in the first place.


>
>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. 

Not particularly. That strikes me as a peculiar way to work in most cases. I think that typically it is more efficient to have a general structure in mind before starting to write--a basic outline of how you plan to approach the subject from the perspective of the audience.

I've worked on many projects where accurate information was chronologically the last element available. But when it finally was available, it fell into a prepared matrix with very little effort on my part.

>
>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. 


That kind of ad hoc design work is a huge waste of everyone's time. Plan first. Write second. Touch up the details if there is time at the end.


>
>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.

Huh?


>
>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.

Great design is an admirable goal, but good, serviceable design should be a basic requirement.


Dick

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.