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
SQL Style Extensions for C#
The Movie Hollywood (And My Wife) Doesn't Want You To See: Weekend at Jacko's
Sysi: the ultimate administrators toolkit
Movie: Priest Academy
Inspirational Rat Story
A face-melting DSL that allows programming ON the iPhone (and iPad)
The secretGeek Disaster Recovery plan
Save KNVTn! Before it's too late
The Ultimate Agent of WERF Destruction
The new prisoner's dilemma
Original Premise for a road movie
What's a better game than Devshop?
DevShop: The Cool Game that Makes Development Look Fun
Should be purple
Kitchen Agile
Perhaps "Go" is the new Visual Basic
zen-coding: turn those CSS selectors upside down
Debugging: It's all about finding Albuquerque.
The Real-Time online JQuery Editor
HTML5, a 3 minute guide
Developer Codpieces
Agile for one: The Personal Story 'Wall' In Action
Never work with thick people.
Cosmo: project status panel
Windows Search in Japan
Project Management Zen
Continuous Integration, Plugins and Going Too Far
The Rules of Stand Up
Sydney International Airport: Stupid, Criminal, or Criminally Stupid?
God No! ...The ReBuilder
Matt, The Office Mortar
'Outlook style' rules for Subversion
Really deep linking: Url + regex
hExcel -- A Hexagonal Spreadsheet
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
Universal Troubleshooting Checklist
Top 10 SecretGeek articles
ShinyPower Now at CodePlex
RealTime Online CSS Editor
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)
|
|
|