Technical Writing: Lower Your Expectations
Sean Goedecke published an excellent set of recommendations for good technical writing, including:
- Keep it short
- Try to make your point in the first sentence
- Details matter less than you think.
Based on some emails I received in the past (and the lack of response to the lengthy emails I sent), we should apply the same rules to emails (and all other forms of technical communication).
I'm partial to that. In spirit, I agree. More often than not, the technical writer writes with a lot of "inside knowledge". The result is exquisite documentation, but only for a person who has spent a lot of time understanding the complex system.
I would take a much more Bayesian approach to tech docs. Have your principal engineer, resident Jedi, wizard, whatever, write the docs, then give the docs to 5 low-level engineers who have never used the system before for a read, and immediately after assess how they use the system. It' freaking revealing.
The author of the article worries too much about what he should write, how much, in what detail, at what level of expectation. In the wild, no one really cares. It's never what you say; it is always what the other hears and perceives. I believe in Bayesian documentation. Documentation that gives you results.
PS: Write scripts where possible. In a complex system, you may come across important tasks that you have to do once in a blue moon, but nevertheless, they must be done. Even if you did it once, you'll probably forget how, the exact syntax, the order of operations ... So first time when you did, just save all the crap in a script.