June 1, 2014

On Documentation, Part 1

A couple of weeks ago the Athletics development team attended BrooklynJS. I was traveling and wasn’t able to make it. We discussed the event when I got back from my trip. The stand out was Brittany Storoz’s talk on technical writing.

This sparked an internal discussion. At Athletics, we come up against the same resource and time constraints that most developers cite as barriers to better documentation. There’s a steady stream of design challenges, site launches, feature requests, and bugs to address. And, as I’m sure you know, many of these things need to be addressed “asap” or, even better, “yesterday”. Given that immediacy and the limited number of hours in a month, it’s sometimes difficult to document code and features as well as we would like to.

So, how do we solve for this? Obviously, there’s no silver bullet. We begin by making documentation a part of process from the very beginning. It should be a line item in our proposals and treated with the same importance as any other component of a project’s scope of work. You can’t call a site finished without writing the stylesheets. The same should go for documentation.

So, if it’s a key component of the scope of work, then we need to put documentation on the schedule and dedicate resources to it. This is where things start to get challenging as different kinds of documentation are best written at different phases of a project. The README is best started at the outset of a project and iterated upon throughout its course. Code documentation is best written inline while the code itself is being written. Feature documentation is best written once a feature is complete and the person responsible for the documentation can step through the feature documenting as they go.

This will be the first entry of four on documentation. Each subsequent entry will cover one of the types of documentation mentioned above – README, code and feature. I’ll describe some of the roadblocks that keep us from writing documentation. I’ll share some solutions that have helped clear these roadblocks and propose others that I haven’t put into practice yet.

I’ll steer clear of reasons why you should write better documentation, how it will make you a better technical writer, etcetera. Your impetus for writing documentation is entirely up to you. My goal is to state problems and present solutions. Like the majority of entries I write here, this is as much about capturing and codifying my own thinking as anything else.

I’ll follow up with an entry on the README in the next day or so and try to roll out the other entires at the same rate.