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

["Sean Brierley" <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.

You see, when they clicked the online help it took them to a particular
topic. For some topics, because the software was not done or because I'd
not doc'ed it yet, a message displayed to the effect that documentation
had not been done.

Adding to the burden was the fact that when the online help was
accessed, the CHM opened without the bookmarks/TOC pane visible. The
thought here was that if someone was accessing a context-sensitive topic
directly, they did not need to browse using the bookmarks/TOC. In fact,
it was possible to click the Show button in the CHM toolbar to show the
bookmarks/TOC, but the person making the accusation had missed this or
was unfamiliar with this.

Along with the CHM at that time there was a PDF that installed with the
beta software and that was available from the Help menu as an "online
book" entry. The person making the complaint missed that, also.

Additionally, nobody else who was beta-testing and QAing the software
and docs spoke up to mention what was available.

So, I was sorta left hanging. Documenting the show-hide button in the
CHM toolbar was one of my first steps. But, later, confusion over
searching in CHMs, using the  index, and using Find in a PDF led to more
documentation.

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

Cheers,

Sean

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

Look at the pages and identify what is actual unique content that tells
the reader something they wouldn't already know about using the product,
compared with the reams of meandering drivel droning on about how to
find information in the document or how to Save a file by going to
File... (on the toolbar that appears at the top of your computer screen)
and using your mouse to move the cursor over top the words that appear
in the drop down file menu that say Save. 

Basically these documents put the customer on an Arthurian quest for the
holy grail of Content.


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

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!

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