How we document stuff

A recurring topic in every software project I've been involved with is what to document, when to do that, and where to store it. So it wasn't a big surprise that at a recent event, somebody asked me how we track and communicate design decisions. I initially pointed him to an article I wrote in February, but then I realized that that one only covers documentation in the context of an evolving architecture. So let me elaborate on documentation a bit more.

In short, we make a distinction between structured and unstructured documentation. We had lots of discussions about that, in particular because some people would really like to introduce a single tool for both of these categories. But I don't believe in silver bullets and prefer to use the best tool for the right job. Neither Microsoft's SharePoint nor Atlassian's Confluence does both well.

Let's start with unstructured documentation. This category covers notes you make during development, usually tightly couple to a user story in Atlassian's JIRA, our tool of choice for agile work item tracking. For those kinds of notes we still use Microsoft OneNote. A great example where OneNote shines is a detailed check list with things that still need to happen within a user story.

We generally start off with a couple of items, but this gets expanded heavily during development. Since we practice Test Driven Development, we track the refactorings, the edge cases and any leftovers here, including the blog post we need to write about some important change we introduced. In my team, having unchecked checkboxes means we still have work to do. So anything that pops up during discussions or sprint demos ends up here. Even if we decide to not do something, I expect the team to track it here. I really feel uncomfortable when open ends are discussed that are not in OneNote. And yes, I still frown upon people that use Notepad to track a couple of notes…

Discussions are also treated as unstructured documentation. For this we use Flowdock, a team-oriented threaded discussion platform, about which I blogged before. Obviously we prefer face-to-face discussions, but with an increasing group of professionals that are less vocal or working remotely, Flowdock has become invaluable to us. Even if we had a face-to-face discussion, we try to add a summary of that to the respective discussion flow, just to allow those that are out-of-office to catch-up the next day. Flowdock is particularly strong because it can serve as an efficient replacement for those long email threads where anybody who has access can read along or decide to participate. You'd be surprised if you see some very valuable contributions from people that would do so during a live conversation.

Related to these discussions we have documentation with semi-structured characteristics; blog posts. Whenever a major architectural, product-wise or process-related change is introduced, the team involved is supposed to write a blog post about that on a SharePoint Blog. SharePoint's WYSIWYG editor really has a lot to wish for and doesn’t support MarkDown. As soon as we find a way to migrate all those posts to Confluence, we'll do. Note that most of the people I know who really treat those posts seriously, write those posts in OneNote so that the team can contribute and provide feedback. We then use Microsoft Word's blog editor to post the final result to SharePoint.

Structured documentation ends up somewhere else. But within that category, we treat product-specific documentation different from project and team documentation. The former is tightly coupled to the version or variant of the product and should follow its development lifecycle. Examples of those are installation guides, (web service and REST) API documentation and release notes. Because of that, we really want people to be able to update that documentation as part of the product or architecture changes happening in the appropriate source control branch. So for that category we use Markdown as well, especially because it's a text-based mark-up, where merging concurrent changes is pretty painless. For editing we either use GitHub's built-in Markdown support or MarkdownPad 2.

Documentation not directly related to stories, products or systems ends up as Confluence pages. Although Confluence can be a bit sluggish sometimes (I suspect Atlassian is still catching up with its popularity), its editing and collaboration features are marvelous. I love getting those emails with recent changes and such. It really allows me to see what's going on within the organization. Architectural or high-level PowerPoint presentations also end up here, but need a special document library to track them. I have the feeling Confluence's integration with Office is not as strong as SharePoint's, but it's acceptable for now. By the way, did I mention that we often create carbon-board posters from those slides? We use them during discussions or as part of the introduction of new people, and also put them on the walls for everyone to see. Those really spark off interesting discussions with new candidates, prospects or existing clients…

So how do you approach software documentation? Let me know by commenting below or tweeting me at @ddoomen.