documentation usability

[John Fleck <jfleck inkstain net>]

Folks -

Prompted by a lot of questions from me, Pat Costello at Sun has
written a helpful document on "Usability and Readability
Considerations For Technical Documentation."

For those who haven't met Pat yet, he's a technical writer who has
been helping Sasha and I put together a GNOME documentation style
guide. His contributions have been terrific, and we hope to have a
draft out soon.

In the process, I posed some questions to Pat about documentation
usability research, and the result was this:

http://developer.gnome.org/documents/usability/

This will be a chapter of the style guide, but in the meantime we
thought it interesting and useful enough to publish on its own.

It offers a number of techniques we can use to help structure our
documents to maximize their usefulness, and some intriguing ways to
try to measure their readability.

(My personal favorite - "You need to create modules short enough to
reduce scrolling or page-turning to an absolute minimum. Your ultimate
aim is to eliminate scrolling or page turning completely for each
individual module of information." He's absolutely right, and this
suggests some docs I need to work on....)

Cheers,
-- 
John Fleck
jfleck inkstain net (h), http://www.inkstain.net/fleck/