How to Write Technical Documentation

Nice post. Thought provking.

Paul’s approach is a good attempt. Seems to be working for him.

Lisa and Beth seem to have a can-do attitude to the situation.

This got a little long as I wrote it, and it’s probably a bit off topic, but what the heck…

In a perfect world, specs would be frozen, use cases would be complete, and clients would be realistic in terms of cost and schedule. (Ha! If you live in that world, consider that you have a great job.)

In the real world that most of us inhabit, none of these is the case. Developers who can’t, or more accurately, refuse to learn to write and speak coherently are the root of this problem. Let’s be honest about the situation – project managers, business analysts, tech writers, and clients aren’t stupid. They just don’t understand code, add we, as developers, shouldn’t expect them to. It’s our responsibility to help them with the technical intricacies that need further explanation.

I hear developers whine all of the time about crappy specs. It’s almost as though developers expect a magical, frozen document to be produced that can be used as the basis for code specifications, technical documentation, user guides, marketing materials, etc., etc., etc. If that kind of document could be written, then what’s the need for developers, tech writers, marketing, etc., etc., etc.??? The work is already done! It’s a team effort, guys. We all need do our part.

If the spec is crap, don’t write code against it until you clarify what you should do. ASK A QUESTION OR TWO. Understand what you are doing. If you don’t understand the purpose of the feature you are writing, and you can’t ask a sensible question, then I wonder what your real value is to your organization.

If all you want to do is code to spec, and you demand a perfect spec, and you’re not willing to ask questions when what you’ve been asked to do doesn’t make sense to you, then you’ve turned your job into EXACTLY the kind of menial work that is being outsourced to India in droves. Developers need STEP UP and become more useful and cooperative team members, or suffer the consequences.

And yes, I am a developer – not a suit. I just refuse to put my name on something that I can not defend. If I don’t know how (and why) it does what it does, pointing to a crappy spec doesn’t help me – it only hurts my co-workers (those PMs and BAs), who I should be supporting. Why would I want to set up a “me vs. them” situation?

Leave the egos at the door. Work for your team’s success, or get the f— out.