Sysadmins CAN write documentation!

Documentation is something that sysadmins are famous for hating to start. Mike Ciavarella is now in year 10 (or 11) of his effort to teach sysadmins that, well...

1. It’s not that bad, really.
2. It’s a really powerful tool.
3. And while you’re honing that tool, here’s how to do it right.

He did open with the case for writing documentation, hooray knowledge retention, including a very good take-down of the “but then they can replace me” argument. Failing to document when asked is something that HR may take official notice of. When it comes time for layoffs, are they going to consider canning the problem employee with a record of insubordination or the junior that’s happy to please? Really, that excuse doesn’t hold water.

And then we dove into the details of writing good documentation. Everything from the workflow of writing to problems common to writing technical documents. Mike even ran us through some examples of converting passive voice to active voice, abstract statements to definite statements, and the other direction as well.

This is a tutorial that really is hard to summarize right. Speaking as someone who does quite a bit of technical writing, though not exactly documentation, I already had a lot of this. But then, there were whole swaths that I only sort of knew but need to get better about. There was useful information in this tutorial for everyone up to people who write doc every day.

One of the biggest points is that you only get better with practice. Set aside some time in your week, every week, to review your doc or add to it. Get better about writing email like Tom Limoncelli talked about Monday, email is documentation that just needs some revision.

Personally, the practice point is well taken. Last time I looked I had over 125,000 words of answers on ServerFault where I’m a moderator. All of that work explaining technical topics to people is practice writing technical documentation. I’ve been blogging since January 2004, which is another form of technical writing. Surprising things can count as practice, and you’ve probably been doing it for years and not noticed that THAT is what you were doing.

Even after all that practice I produce good doc, but it clearly has room for improvement. Mike will be back next year, look this tutorial up if you haven’t before.