Technical Writing: 10 Mistakes you don't wanna make

These are not the most common mistakes -- but they may be the nastiest.

1. Avoid personal pronouns, and reminiscence:

   "Your first COM+ application will be a challenge. For me it was a comic travesty, akin to my first sexual awakening."

   
   
2. Avoid stale or dated metaphors:

   "The ASP.net worker process is the busy housewife of the computing kitchen."

   
   
3. Beware of similes:

   "Using exceptions to control the flow of a program is like using a small tonne of dynamite to light a toddler's birthday candle."

   
   
4. Avoid Florid Speech:

   "Pray, my gentle reader, that the maintenance programmers who swim unto your fetid wake do not, upon their puppy-fat arms, still wear the flotation devices of ineptitude."

   
   
5. Avoid religious topics:

   "... Linux ..."

   
   
6. Don't assume your reader to be technically ignorant:

   "When designing COM+ applications (by 'applications' I mean a collection of bits and bobs on your computer [by 'computer' i mean that brace of machinery hunkered down on your desk {by 'desk' I mean that flat surface on which..."

   
   
7. Avoid offensive pronouns:

   "Beware of XSLT, she is a fussy bitch."

   
   
8. Avoid Personalization (anthropomorphism) :

   "The garbage collector floats above the sleeping memory heap, seeking whom he may devour..."

   
   
9. Cut overlarge words; break over-long sentences:

   "Overtly de-ontological programming didactaphiles may decant nefariously on the disturbing obfuscations that arise from perturbations of the index within a vigorously nested loop, but a less..."

   
   
10. Avoid the "not un-" construct (this example courtesy of Orwell) :

    "A not unblack dog was chasing a not unsmall rabbit across a not ungreen field."

    
    

Actually, I quite like a few of those... Particular metphors and similes...

My book "Choose Your First Product" is available now.

It gives you 4 easy steps to find and validate a humble product idea.

Learn more.