What's Doc, Pal?

P. J. Connolly began writing for IT publications in 1997 and has a lengthy track record in both news and reviews. Since then, he's built two test labs from scratch and earned a reputation as the nicest skeptic you'll ever meet. Before taking up journalism, P. J. was an IT manager and consultant in San Francisco with a knack for networking the Apple Macintosh, and his love for technology is exceeded only by his contempt for the flavor of the month. Speaking of which, you can follow P. J. on Twitter at pjc415, or drop him an email at pjc@eweek.com.
By P. J. Connolly  |  Posted 2011-08-25 Email Print this article Print

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.

Internet Connect

Although configuring a Mac to use a VPN link is easy enough, it really helps to have the details in one document.

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.

del.icio.us | digg.com

Submit a Comment

Loading Comments...

Manage your Newsletters: Login   Register My Newsletters

Rocket Fuel