Re: New Year's Documentation Quality Resolutions

["Peter Ring, PRC" <prc -at- ISA -dot- DKNET -dot- DK>]

Jim Snowden wrote:

> My goal is that our documentation would be called "Excellent" by all its
> users. I've put down some ideas here of what that might mean and would
> be glad for any feedback from other techwhirlers.
>
> In order to achieve that goal, we need to ensure the documentation has
> these general characteristics:
>
> ACCURATE:
> Technically accurate.
> Typographically accurate - having good style guidelines, and conforming
> to those guidelines.
> Grammatically accurate - good spelling and sentence construction.
> Complete - covers all aspects of the product (bearing in mind the
> readership)
> Up-to-date - covers the product release the customer is using.
> Consistent - uses consistent terms and typographical style.
> Maintainable - easy to update the source files with minor and major
> product changes, and to publish
>
> APPROPRIATE:
> Accessible - required information can be found with minimum of time and
> effort.
> Available - required information is always available when the reader
> needs to find it.
> Understandable - when found, the information can be understood and acted
> on by the reader.
> Attractive - the information gives a "first impression" reassurance to
> the user that it is going to be clear and helpful.
> Elegant - the information is presented in a pleasing way that give the
> appearance of quality.
> Useful - the information is what the reader needs to know.
>
> I could have put in "all our end-user docs will be done in HTML Help" or
> "ustomers will be able to download updates from the web". But I'm trying
> here to get some qualities of excellent information, and then from those
> work out how best to attain those qualities for our range of readers.

It's definitely a good list, covering a lot of very important points
+ some points which are relevant for some companies, only, e.g.
"elegant". I also agree with the comments by John Wilcox:

> 1.  Add "concise."  Get to the point in as few words as possible.

> 2.  Move "useful" to the top of the list.  Prime Directive:
> Consider the audience, and write to _their_ needs.

But I don't hope it is representing your priority order, because
here I will put John Wilcox's point 2 first (the "consider the
audience part"), followed by his point 1 and then Jim's three first
APPROPRIATE points on top with the third point first.

Bear in mind that these points need not to be covered by the skills
of one person, only, it may very well be the happy result of the
collaboration between many persons, e.g. the writer, the proofreader,
the graphics designer, and last but not least the designing
engineer(s).

In order to cover more aspects of the subject, and to convert the
goals into practical daily routines, I will recommend you to take a
look at my "User Friendly Manuals Website" at
http://isa.dknet.dk/~prc, especially the "Tip of the Month" for
December 1997 and the page about my book. Depending of your company's
products and the kind of manuals you make, a number of the old tips
may also be of interest to you, see the list of "Old tips".

I wish you all a merry/happy <what you personally celebrate on this
time of the year>.

Greetings from Denmark

Peter Ring
PRC (Peter Ring Consultants)
- specialists in user friendly manuals and audits on manuals.
prc -at- isa -dot- dknet -dot- dk
http://isa.dknet.dk/~prc/
- the "User Friendly Manuals" website with links, bibliography, list
  of prof. associations, and tips for technical writers.


	http://www.documentation.com/, or http://www.dejanews.com/