fantasai wrote: > 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? I meant limit procedures to seven steps. Research has shown that that is the optimal amount in a procedure to be best understood. Interestingly it seems to be about the same in computer procedures. > > >>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> Is that an example of what to do or what not to do?
-- Brant Langer Gurganus The key to success is to climb the ladder instead of sitting and waiting for the elevator. http://troop545.cjb.net/brant.htm
