Re: Benchmarking Technical Documentation

Subject: Re: Benchmarking Technical Documentation
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 23 Jul 2001 14:55:25 -0400

Richard Smith wrote:
>
> > Unfortunately, they can't tell me exactly WHY the documentation
> > is so good.
>
> This shouldn't be very hard to communicate. All good docs share one common
> thread. They contain the information users need. That's all.

That is by no means all. If you said "They make the information users need
readily accessible", then I'd agree, but just comtaining the info users
need is not nearly enough.

Organisation is essential:
The information doesn't just have to be there, it must be organised so it
makes sense and things are findable.

Indexes and cross-references are vital:
Users often need to find only some small bit of info. Good docs make it
possible to do this efficiently.

Format is important:
For example, you might deliver exactly the same info in several paragraphs
of complex text or in an easily-scanned table.

> I've heard people say that things like typos, bad grammar, incorrect usage,
> etc. all will cloud the credibility of a doc. That's a load of you-know-what
> IMO. If I need to know the jumper settings to get board X to work, do I care
> if it sounds like it's written by a third grader? No. Do I care if the file
> is a PDF that makes me scroll three pages to the right? Not if it gets the
> board working for me.
>
> Don't take that to mean the spelling and grammar don't matter. Take it to
> mean that most users, while they will gleefully point such errors out to
> you, care most about finding the content they need. That's what makes a
> document good. Usability, readability, format, and style are all icing on
> the info-cake.

I'd say having the info is a basic requirement. Without it, the doc is
rubbish. For a good doc, you need usability. Anything beyond that is
icing.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


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


References:
RE: Benchmarking Technical Documentation: From: Richard Smith

Previous by Author: Re: Salary - It's Easy
Next by Author: Re: Any special advantages for...
Previous by Thread: RE: Benchmarking Technical Documentation
Next by Thread: RE: Benchmarking Technical Documentation


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


Sponsored Ads