Technical Writing: 10 Mistakes you don't wanna make
These are not the most common mistakes -- but they may be the nastiest.
- 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."
- Avoid stale or dated metaphors:
"The ASP.net worker process is the busy housewife of the computing kitchen."
- 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."
- 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."
- Avoid religious topics:
- 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..."
- Avoid offensive pronouns:
"Beware of XSLT, she is a fussy bitch."
- Avoid Personalization (anthropomorphism) :
"The garbage collector floats above the sleeping memory heap, seeking whom he may devour..."
- 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..."
- 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...
Add or view comments about this page
|
Articles
Is the remote control a thing of the past?
The Utterly Thorough Guide To Awesome Application Compatibility on Windows 7.
Astounding Hyperlinked Noticeboard
Three Questions About Each Bug You Find
Recursing over the Pareto Principle...
Sometimes, The Better You Program, The Worse You Communicate.
.: secretGeek :: Complete Archives
TimeSnapper.com
Version 3.3: true productivity boost
NextAction Managing the top of your mind
World's Simplest Code Generator
25 steps for building a Micro-ISV
3 Minute Guide Series
Top 10 SecretGeek articles
ShinyPower Now at CodePlex
Gradient Maker
How to be depressed
You are not inadequate.
Recommended Reading
The Best Software Writing I
The Business Of Software (Eric Sink)
Recommended blogs
Jeff Atwood
Reginald Braithwaite
Joseph Cooney
Phil Haack
Scott Hanselman
Julia Lerman
Rhys Parry
Joel Pobar
OJ Reeves
Eric Sink
Joel Spolsky
Des Traynor
Aggregated Links
programming.reddit.com
dzone
dot net kicks
Human Link Machines
interesting finds
a continuous learner's weblog
arjan's world
n links today
new and notable
morning coffee
learning .net
weekly link post
(my del.icio.us account)
|
|
|