How to Write Technical Documentation

Let’s talk about let’s face it.

In IT, most people suck at their jobs. Believe it or not, even technical writers. Most work I have seen done by those in the technical writing trade has been generally inadequate and unnecessarily verbose. Dually, most engineers also write bad code and even worse documentation. But the fact of the matter is, that the reason all of you technical writers have so much crap to deal with is companies that do operate smoothly do not have a need to hire technical writers.

In my organization – a place where like all others things are very far from perfect – we do not hire technical writers. We instead have product and project documentation guide lines, function and technical specification reviews (of the show stopping nature) and as engineers run requirements gathering documentation in parallel to functional specifications drafting. The end result is a product that we know how it works, and how it works is documented. (There are legacy exceptions to the rule, but we do what we can when we have time to incrementally repair that).

And thus my point, since when engineers are good at their job and the engineering staff is lead by someone who is specification oriented, technical writers are rarely if ever necessary. Thus, technical writers are bound to hate their jobs – because they are called in to companies that have no clue how their product works, and don’t have anything that tells them, and don’t have time to iron it out. This criteria for requiring a technical writer leads you into the darkest deepest crud-holes of medium/large size companies world wide.