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.
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. 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>
<ul>
<li>subdivide your document and outline it with headings
<li>organize a strong structure
<li>use lists
<li>write concisely; don't ramble
<li>get to the point first, then elaborate
<li>don't write long introductions except in "Introduction"
sections
<li>give a clear explanation
<li>and use specific examples to illustrate the text.
(An example is worth a thousand words.)
</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>
</div>
