Documentation

We're nearing the end of the testing cycle for a product release. There aren't any high priority bugs around so I was told to just grab some lower priority issues. Given a choice I decided to tackle some documentation that had become a little bit out of date.

I find I've enjoyed doing the documentation. There's a certain Zen to documentation that makes it satisfying. Maybe it's because, like code, it can be verified to be correct. Plus I'd been involved in this documentation in earlier releases so it was something that I'd been involved with in the past that I wanted to see maintained at a high level of quality.

Documentation, especially API documentation, unlike code, can generate feedback from external users. Nobody ever sees the code you write, especially outside the programming group. But with documentation you are presenting yourself and your department for external valuation. Do a good job and you'll look good and be praised. Do a shoddy job and probably nobody will say anything directly, but the bad vibe will come back around in some way.

Around 10 years ago my younger sister was finishing up high school and considering her options heading into university. I encouraged her then to get into technical writing. She can write, and could learn the technical jargon easily enough. There were about a million tech jobs open at that time. It's much easier to teach natural writers the technical stuff than to try to teach people how to write well. You either can or you can't write.

She ended up going to law school and has had a good career. If I wasn't programming, then maybe I would have got into technical writing. I probably would have enjoyed it enough as a vocation.