On 11 Jul 2002, it is alleged that fantasai sauntered in to
netscape.public.mozilla.documentation and loudly proclaimed:
> Brant Langer Gurganus wrote:
>>
>> I am looking for tips to put in a "Tips for Effective Documentation"
>> document. Here are some examples:
>> * Keep procedures at seven steps.
>
> Why? Shouldn't the division into steps be based on where the division
> naturally falls instead of some arbitrary target number?
>
>> Please reply with your suggestions.
All of this is of course open to debate. :-)
> Use lists. If the information fits into a list, don't add fluff to make it
> a paragraph. Example:
>
>
> <div class="para">
> <p>When writing technical documentation, especially online
> documentation, strict organization assumes a particularly
> important role.
That's generally the case when it comes to /any/ kind of documentation.
Unfortunately, you seem to've fallen into a set of mistaken assumptions I
find far too often when it comes to writing on-line documentation (which I
tend to find of inferior quality to hard documentation).
> The reader is often there only to find some
> specific piece of information and typically scans rather than
> peruses the text. To make this easier,</p>
You have no idea how often I come across this. I swear, what most people
seem to want is nothing but lists of verb/noun pairs.
I would say that reading on-screen is in fact epistemologically different
reading from a printed page. I have tended to approach the issue by using
shorter paragraphs of a sentence or two, as one would find in a newspaper.
The goal, finally, is the same whether one is working with the printed page
or with something designed to be read on-screen.
> <ul>
> <li>subdivide your document and outline it with headings
You might want to add that the basic structure should be evident from any
introductory material. It's not necessary to replicate the structure in a
kind of ToC save in the case of longer docs that might span several pages.
> <li>organize a strong structure
Depending on the type of documentation, however, this may be easier said
than done.
> <li>use lists
But use them *sparingly*; too often writers fall back on lists thinking
they're actually conveying information when in fact all they're doing is
paraphrasing things and not making information clear.
> <li>write concisely; don't ramble
That said, however, beware of the trap of writing *too* concisely; give all
the information that is necessary. Giving too little information is as bad
as rambling endlessly.
The second trap of concision is that writers tend to fall into repetitive
grammatical patterns. This is a bad thing, and is in fact one of the
inherent problems with lists, which encourage a certain grammatical
uniformity.
> <li>get to the point first, then elaborate
Again, this can tend towards a repetitiveness in one's presentation of
information, but it really does depend on the nature of the information
being presented. The information should determine the way in which it is
presented.
> <li>don't write long introductions except in "Introduction"
> sections
That's fair 'nuff.
> <li>give a clear explanation
This can serve as an instance of how lists can prevent an explantion from
being clear. ;-)
> <li>and use specific examples to illustrate the text.
> (An example is worth a thousand words.)
As necessary, of course.
> </ul>
> <p>You want the main points of your writing to stick out so
> that the reader can find the right section quickly and easily.
> Snag them first, then explain.</p>
Most often, yes. There are various ways in which to go about this. (BTW,
fantasai, this is part of my problem with structural/semantic tags: there
are time I want to highlight information in a purely physical/presentational
way, and often the rationale for doing so is simply to give a bit of
guidance to a reader who might just be skimming the text.)
> </div>
/b.
--
Mozilla end-user questions should be directed to:
snews://secnews.netscape.com:563/netscape.mozilla.user.general
snews://secnews.netscape.com:563/netscape.mozilla.user.win32
snews://secnews.netscape.com:563/netscape.mozilla.user.mac
snews://secnews.netscape.com:563/netscape.mozilla.user.unix
Note that you need to have SSL enabled and the port set to 563.
