Technical Writing: breadth first with iteration.
secretGeek .:dotnuts about dotnet:.
home .: about .: sign up .: sitemap

Technical Writing: breadth first with iteration.

No truly sane developer enjoys writing user documentation. This is a short note about fulfilling your obligation to write technical support documentation. Originally it was a comment on Roy Oshergrove's 'Iserializable' blog. Roy seemed to like it, so I've republished it here.

Writing, whether technical or creative, always has defects. It never has the elegance of code, it can never be evaluated completely. There are always more ways you can look at it.

So accept that it's going to be bland and imperfect and boring. Accept that very few people are going to read it or refer to it. All you have to know is that when people do, they'll be able to get nice simple instructions that will lead them to the answer they are looking for.

Use lots of sub headings. Sub headings are easy to write. (if you can't even write the subheadings then you're really in trouble) write enough sub headings the thing is practically done. That's your first draft. Print it out. Give yourself a pat on the back.

Write very quick notes under each sub heading. print it out and re-read it, judging it only for its truthfulness and its completeness. Do not parse it for grammar, style, sophistication, sexiness or anything else. Where it isn't complete, add more notes. Where it isn't truthful, make it truthful. Ugly is fine. Stupid is okay. Boring is expected. Just make it truthful and complete. Now print that out. that's your second draft. You've earned another pat on the back.

Now track down your sub-editor. This is probably your wife/secretary/mother - someone who is not your boss, who loves you unconditionally, who is not as technical as you (they're NOT concerned with the facts or the completeness of what you've written.) Plead with them until they agree to read through it with you. They love you unconditionally, so they will agree. They won't hate what you've written, but they'll know which problems of style are the important ones. And once you've read it through with them, you will too. The third draft's the charm. Once that's done, send it out into the world. You've wasted enough time already.

cheers
Leon bambrick
http://www16.brinkster.com/messydesk/db/index.asp


Add or view comments about this page

Articles

A Computer Simulation of Creative Work, or 'How To Get Nothing Done' A Computer Simulation of Creative Work, or 'How To Get Nothing Done'
NimbleText 1.9 -- BoomTown! NimbleText 1.9 -- BoomTown!
Line Endings. Line Endings.
**This** is how you pivot **This** is how you pivot
Art of the command-line helper Art of the command-line helper
Go and read a book. Go and read a book.
Slurp up mega-traffic by writing scalable, timeless search-bait Slurp up mega-traffic by writing scalable, timeless search-bait
Do *NOT* try this Hacking Script at home Do *NOT* try this Hacking Script at home
The 'Should I automate it?' Calculator The 'Should I automate it?' Calculator
aaron swartz: the early works aaron swartz: the early works
Finding (and removing) duplicate files on your hard drive Finding (and removing) duplicate files on your hard drive
Harvey, a .net chat server built with RabbitMQ Harvey, a .net chat server built with RabbitMQ
LeonBambrick.com LeonBambrick.com
So your domain has been stolen. What now? So your domain has been stolen. What now?
kv can remember it for you, wholesale kv can remember it for you, wholesale
Hello IT Department Hello IT Department
Dialog Between a Man and His Vista Laptop Dialog Between a Man and His Vista Laptop
NimbleText 1.6, Codename Jetboat NimbleText 1.6, Codename Jetboat
On Task Hoarding and Todo Bankruptcy On Task Hoarding and Todo Bankruptcy
Developer UI Done Right: Mercurial Commandline! Developer UI Done Right: Mercurial Commandline!
Rediscovering the Amstrad CPC 6128 Rediscovering the Amstrad CPC 6128
Just Wally Just Wally
The Correct Order for a First Time Viewing of The Lord Of The Rings The Correct Order for a First Time Viewing of The Lord Of The Rings
A new era for Android. A new era for Android.
Mind-boggling Demo of New Gaming Genre, aka Folder-Based Hangman, aka Fun with Recursion Mind-boggling Demo of New Gaming Genre, aka Folder-Based Hangman, aka Fun with Recursion
Got CSV in your javascript? Use agnes. Got CSV in your javascript? Use agnes.

Archives Complete secretGeek Archives

TimeSnapper -- Automated Screenshot Journal TimeSnapper: automatic screenshot journal

25 steps for building a Micro-ISV 25 steps for building a Micro-ISV
3 minute guides -- babysteps in new technologies: powershell, JSON, watir, F# 3 Minute Guide Series
Universal Troubleshooting checklist Universal Troubleshooting Checklist
Top 10 SecretGeek articles Top 10 SecretGeek articles
ShinyPower (help with Powershell) ShinyPower
Now at CodePlex

Realtime CSS Editor, in a browser RealTime Online CSS Editor
Gradient Maker -- a tool for making background images that blend from one colour to another. Forget photoshop, this is the bomb. Gradient Maker


[powered by Google] 


How to be depressed How to be depressed
You are not inadequate.



Recommended Reading


the little schemer


The Best Software Writing I
The Business Of Software (Eric Sink)

Recommended blogs

Jeff Atwood
Joseph Cooney
Phil Haack
Scott Hanselman
Julia Lerman
Rhys Parry
Joel Pobar
OJ Reeves
Eric Sink

Aggregated Links

proggit
dzone
hacker news
dot net kicks

Human Link Machines

interesting finds
a continuous learner's weblog
arjan's world
weekly link post

LinkedIn profile
LogEnvy - event logs made sexy
Computer, Unlocked. A rapid computer customization resource
Aussie Bushwalking
BrisParks :: best parks for kids in brisbane
PhysioTec, Brisbane Specialist Physiotherapy & Pilates
home .: about .: sign up .: sitemap .: © Leon Bambrick 2003 .: privacy

home .: about .: sign up .: sitemap .: © Leon Bambrick 2003 .: privacy