Documentation Needs Organization

Dec 13 2008

So, I'm taking over the technical management of a web service. One of the first things I did was talk to everyone, mostly to check the temperature. The kinds of questions I asked were basic. If you ask a basic question, you get a better answer. And one of those questions was What can we do better? The one unanimous issue was that we needed better documentation.

Great. Only two problems with this. Most of the team doesn't write well. In the past, nobody has gone out of their way to really make documentation happen. Why I point this out: most teams probably think that this is just a scheduling problem. As if you just added some time for Documentation, the problem is solved. I think if you just added more time for documentation, people will just half-ass some crap on the wall and probably spend the rest of the time you slated for documentation surfing the intertubes.

I need a strategy. I need a system that will help bad writers get better incrementally. Which means that everything must be painfully obvious. The first pieces of the puzzle are the stuff that actually exists, which are the most important parts, anyway.

• Code/API Documentation - What does your code do? Especially, what side effects are there?
• Adminsitration Guide - How do we run the system?
• Users Guide - How do users run the system?

The other part is planning. Essentially, you need to identify groups of features, and then answer two big questions for each feature set.

1. What's the business value here? Or, how do we get paid?
2. How is this thing going to work?

I'm not sure I've not forgotten about something.

Six-Month Update — June 2009

The organization over the last few months have yielded the following changes:

1. Checklists were created, which are being used.
2. The administration guide moved into [Markdown] documents, and are not being used.
3. We're using Markdown for our web API documentation, which actually looks nice. We'll likely use it for user guide documentation.
4. Internal API Documentation, like JavaDoc and ScalaDoc, are not used.

The chief problems with the internal API documentation are that it's very hard to use. While programming, it requires opening up a new window, and then creating a much less convenient navigation system. Scroll scroll scroll. Plus, if you split your project up into many projects, that usually means many different sites. Click click click.

The problem is that our editors have become to fast for navigation. In TextMate, I just hit Command-T and then type in a class name, and poof! Source! The only drawback is that the code navigation is a little tricky, as you get both public and private stuff in the same view. Schade.

So we'll see.

Planning Documentation Fail

As of today, I can not figure out a great way to get planning going. We get far too sidetracked, and it is impossible to generate interest in anything the programmers are producing by anyone in the sales organization.

Also, it's been really difficult to get a good project management system going. I tried using hourly tracking in our JIRA tool, but it's too tedious, and I can't keep track of who didn't write something in. But there's a better

So, at this point, the planning documentation probably needs to be organized around the team workflow:

1. Tickets, because we have a good ticketing system
2. Internal Marketing, which summarizes the tickets and gets people exited