Technical Documentation: How it really gets written
This reputedly originates from Damien Katz of The CouchDB Project:
"Welcome to the world of technical documentation! The situation you are in is no different from any other technical author. The technical writing process:
1. Ask engineer how the damn thing works.
2. Deafing silence.
3. Crickets.
4. Tumbleweed.
5. Just start writing something. Anything.
6. Give this something to the engineer.
7. Watch engineer become quite upset at how badly you've missed the point of everything.
8. As the engineer berates you, in between insults he will also throw off nuggets of technical information.
9. Collect these nuggets, as they are the only reliable technical information you will receive.
10. Try like hell to weave together this information into something enlightening and technically accurate.
11. Go to step 6. "
I can't say it's true in our experience, but I can imagine situations where it could be.
Labels: technical author, technical documentation
posted by Ellis @ 2:20 PM
4 comments
4 Comments:
This is pretty accurate for some of the contracts I've worked on.
Sometimes the silence, crickets and tumbleweed are replaced by "I dunno, it's pretty intuitive really."
That's about when I just start writing and see what sticks - at least for round one.
Pretty accurate? That's dead-on!
This post has been removed by the author.
oh yeah. I have just made stuff up about how I THINK something should work. Then I'd hand it over, get yelled at, and finally get some real information.
Post a Comment
<< Home