[Tutor] Advice required: Documentation Writing / Sofware
Testing
Bob Gailer
ramrom@earthling.net
Thu Dec 19 19:36:01 2002
--=====================_27814705==.ALT
Content-Type: text/plain; charset="us-ascii"; format=flowed
Gailer's Guidelines for Applaudable Documentation:
0 Ensure that management is committed to quality documentation. Help create
a quality assurance guideline, and commitment to adhering to it.
1 Use active rather than passive verbs (e.g. "push the button" rather than
"the button is pushed")
2 Talk directly to the reader (e.g. "you" rather than "the user")
3 Be brief (e.g "rename changes the name of a file" rather than "rename
enables the user to ...")
4 Be consistent. If you use a certain term to refer to something, always
use exactly the same term. You are writing a technical document, not a novel.
5 Avoid italics or quotes as the sole attempt to tell the reader that this
is a new term. Whenever introducing a new term, explain it the first time.
6 Be complete and accurate. If documenting a command explain all the
ramifications. Note that, among others, Microsoft's documentation almost
always fails to explain everything a command does, and often has errors in
the explanation. That costs each reader lost time experimenting an
debugging. If a command can raise errors, list the errors with the command.
7 Provide a glossary that explains all technical terminology that is
specific to whatever you're documenting, and any terms that might be
outside the range of knowledge of the intended reader.
8 Different readers have different strategies for searching the index. So
index things under various headings to make it easy for anyone to find what
they're looking for. Also include references to chapter and section
headings in the index. It can be very frustrating to (1) search the index,
then have to look in the TOC (table of contents) to find the term.
9 Indicate e.g. by bolding the page number(s) in the index that are the
main references for a term.
10 Understand the differences between e.g. and i.e., between effect and affect.
11 Be complete (2). Ensure (same as insure) that everything the reader
needs to know is covered.
12 When documenting commands and functions, use meaningful names for
parameters (arguments). Bad example:
find <string1> <string2>. This forces the reader to look below to
ascertain which argument is the string to be searched and which is the
string sought. IBM handled this beautifully: find <needle> <haystack>.
13 Teach management and technical people the importance of quality
documentation. Good documentation helps create happy customers, and reduces
the need for technical support. Since many companies charge $$$ for
technical support, this may be a conflict of interest, but customer
satisfaction should come first.
14 Have technical sections reviewed by the responsible coder, engineer,
designer.
15 Create a mechanism for keeping this current.
16 Use revision bars and a section that documents all changes from previous
edition.
17 Publish on-line, and keep the on-line documentation up-to-date. It is a
lot easier for users to read up-to-date documentation, than to wade through
1000s of articles to see what has changed. If this is done religiously the
on-line documentation can be the next edition when going to press.
There's probably more to say. Let me know if this helps. If you want
further services in independent review of documentation and ideas for
automating some of the above let me know.
Bob Gailer
mailto:ramrom@earthling.net
303 442 2625
--=====================_27814705==.ALT
Content-Type: text/html; charset="us-ascii"
<html>
<body>
Gailer's Guidelines for Applaudable Documentation:<br>
0 Ensure that management is committed to quality documentation. Help
create a quality assurance guideline, and commitment to adhering to
it.<br>
1 Use active rather than passive verbs (e.g. "push the button"
rather than "the button is pushed")<br>
2 Talk directly to the reader (e.g. "you" rather than "the
user")<br>
3 Be brief (e.g "rename changes the name of a file" rather than
"rename enables the user to ...")<br>
4 Be consistent. If you use a certain term to refer to something, always
use exactly the same term. You are writing a technical document, not a
novel.<br>
5 Avoid italics or quotes as the sole attempt to tell the reader that
<i>this is a new term</i>. Whenever introducing a new term, explain it
the first time.<br>
6 Be complete and accurate. If documenting a command explain all the
ramifications. Note that, among others, Microsoft's documentation almost
always fails to explain everything a command does, and often has errors
in the explanation. That costs each reader lost time experimenting an
debugging. If a command can raise errors, list the errors with the
command.<br>
7 Provide a glossary that explains all technical terminology that is
specific to whatever you're documenting, and any terms that might be
outside the range of knowledge of the intended reader.<br>
8 Different readers have different strategies for searching the index. So
index things under various headings to make it easy for anyone to find
what they're looking for. Also include references to chapter and section
headings in the index. It can be very frustrating to (1) search the
index, then have to look in the TOC (table of contents) to find the
term.<br>
9 Indicate e.g. by bolding the page number(s) in the index that are the
main references for a term.<br>
10 Understand the differences between e.g. and i.e., between effect and
affect.<br>
11 Be complete (2). Ensure (same as insure) that everything the reader
needs to know is covered.<br>
12 When documenting commands and functions, use meaningful names for
parameters (arguments). Bad example:<br>
find <string1> <string2>. This forces the reader to
look below to ascertain which argument is the string to be searched and
which is the string sought. IBM handled this beautifully: find
<needle> <haystack>.<br>
13 Teach management and technical people the importance of quality
documentation. Good documentation helps create happy customers, and
reduces the need for technical support. Since many companies charge $$$
for technical support, this may be a conflict of interest, but customer
satisfaction should come first.<br>
14 Have technical sections reviewed by the responsible coder, engineer,
designer.<br>
15 Create a mechanism for keeping this current. <br>
16 Use revision bars and a section that documents all changes from
previous edition.<br>
17 Publish on-line, and keep the on-line documentation up-to-date. It is
a lot easier for users to read up-to-date documentation, than to wade
through 1000s of articles to see what has changed. If this is done
religiously the on-line documentation can be the next edition when going
to press.<br><br>
There's probably more to say. Let me know if this helps. If you want
further services in independent review of documentation and ideas for
automating some of the above let me know.<br>
<x-sigsep><p></x-sigsep>
Bob Gailer<br>
<a href="mailto:ramrom@earthling.net" eudora="autourl">mailto:ramrom@earthling.net</a><br>
303 442 2625<br>
</body>
</html>
--=====================_27814705==.ALT--