RE: doc'ing the docs (was RE: Hackos' minimalism seminar -- some insights)

[KMcLauchlan -at- chrysalis-its -dot- com]

Hah!  I don't do online help, at this time, just 
print and PDF docs, but I too was bitten on the 
butt when I assumed that the reader would just 
"get it".

After a flurry of complaints from my reviewers, 
I returned to my usual practice of including a 
few pages in the Intro, saying what the various 
icons and fonts represented, and also a brief 
roadmap of the document set: "you need *this* 
document for initial setup; you need that document 
for maintenance and infrequently used operations; 
you need that other doc for integrating with these 
particular third-party systems that we have tested;
you may find the API/SDK doc handy if you are 
rolling your own..."

The reviewers are happy again.  The Beta customers, 
and those regular customers who don't squirm too 
much when asked such questions,.... are happy. So, 
I'm happy to (minimally) doc the docs.

/kevin

> -----Original Message-----
> From: Sean Brierley [mailto:sbri -at- haestad -dot- com]
[...]
> Don't overestimate your audience.
> 
> I never used to pay much mind to doc'ing the docs either. Until it bit
> me in the rear. At a company meeting, with the owner, I was accused of
> not having a draft of the documentation done.

[snip about online help]
 
> All of my testers, QAers, and audience have a BS, or higher (many are
> phDs), and are used to working with software.
> 
> Thus, sometimes doc'ing the doc is a good idea. Don't assume that your
> audience, even people used to working with software, are really savvy
> enough or have the patience to look at the interface and 
> figure it out.
> Common sense, if that's what this is, isn't always what you 
> think . . ..

> -----Original Original Message-----
> From: Dave Neufeld [mailto:Dave_Neufeld -at- spectrumsignal -dot- com] 
> 
> I would say some writers even spend (waste) oodles of time, pages and
> the customer's time writing about how to navigate their document. Page
> after useless page of how to move around in the document, and no
> content. 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

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