What’s Doc, Pal?

I’ve always been a bit obsessive about documentation, and that mindset comes in handy. For example, I spent a couple of hours this morning reviewing the steps for configuring a Mac to use our corporate VPN and putting them into handout form. This document should already exist somewhere in the files of the IT department, but between entropy and staff shuffles, the tribal knowledge only existed as an e-mail thread from many months ago.

[WP_IMAGE]

This is the sort of thing I love; it’s a break in the routine, and sates whatever latent public service genes I may carry. It’s less amusing when I spend a couple of minutes trying to point a machine to an IP address that is no longer valid, because I didn’t read all of the e-mail thread; but that’s a lesson I have to relearn every week.There’s something terribly satisfying about reducing a complex interconnection of hardware and software into a three-step handout. The quandary I always find myself in when writing end-user documentation is one of how much information to provide.

For this project, I didn’t need to include a primer on VPN technologies, because nobody outside of IT cares about the details. I could have explained what the command-line sequence was doing in greater detail than “point to a specific server” but that’s another bucket of unnecessary detail I chose to avoid.

In a nutshell, that’s the tricky part about writing documentation: you have to know your audience. I enjoy excruciating detail; few others do.