How to Write Technical Documentation

Jeff Atwood

25 Aug 2006 — 1 min read — Comments

I was browsing around the CouchDb wiki yesterday when I saw Damien Katz' hilarious description of how technical documentation really gets written. You know, in the real world:

Welcome to the world of technical documentation!

The situation you are in is no different from any other tech writer. The technical writing process:

Ask engineer how the damn thing works.

Deafing silence.

Crickets.

Tumbleweed.

Just start writing something. Anything.

Give this something to the engineer.

Watch engineer become quite upset at how badly you've missed the point of everything.

As the engineer berates you, in between insults he will also throw off nuggets of technical information.

Collect these nuggets, as they are the only reliable technical information you will receive.

Try like hell to weave together this information into something enlightening and technically accurate.

Go to step 6.

Ok, you're not the doc writing type. That's okay, neither am I. However, people are already working to make this better, and I will continue to do so.

I think I've been on both ends of this exchange at some point in my career. It's funny because it's true. I'm sure I've read descriptions exactly like this on Mike Pope's blog.

If I haven’t blogged much in the last year, it’s because we’ve been busy building that civilized discourse construction kit thing I talked about. (Yes, that’s actually the name of the company. This is what happens when you put me in charge of naming things. Pinball

The Rule of Three

Every programmer ever born thinks whatever idea just popped out of their head into their editor is the most generalized, most flexible, most one-size-fits all solution that has ever been conceived. We think we've built software that is a general purpose solution to some set of problems, but

Today is Goof Off at Work Day

When you're hired at Google, you only have to do the job you were hired for 80% of the time. The other 20% of the time, you can work on whatever you like – provided it advances Google in some way. At least, that's the theory. Google&

Coding Horror: The Book

If I had to make a list of the top 10 things I've done in my life that I regret, "writing a book" would definitely be on it. I took on the book project mostly because it was an opportunity to work with a few friends

Recent Posts

Stay Gold, America

We are at an unprecedented point in American history, and I'm concerned we may lose sight of the American Dream.

The Great Filter Comes For Us All

With a 13 billion year head start on evolution, why haven’t any other forms of life in the universe contacted us by now? (Arrival is a fantastic movie. Watch it, but don’t stop there – read the Story of Your Life novella it was based on for so much

I Fight For The Users

If you haven’t been able to keep up with my blistering pace of one blog post per year, I don’t blame you. There’s a lot going on right now. It’s a busy time. But let’s pause and take a moment to celebrate that Elon Musk

The 2030 Self-Driving Car Bet

It’s my honor to announce that John Carmack and I have initiated a friendly bet of $10,000* to the 501(c)(3) charity of the winner’s choice: By January 1st, 2030, completely autonomous self-driving cars meeting SAE J3016 level 5 will be commercially available for passenger use