Documentation management (not document management!) is the rather narrow topic of how a development team manages the system specifications that are used throughout the life of a system. In most teams, this is a huge blind spot with some teams simply not documenting much of anything and others spending an enormous amount of time (money) creating and updating documents. As Joel on Software mentioned waay back in 2000, this is bad.
As with most things, striking a balance is a nice goal, but this can be tough with documentation. Without a dedicated technical writer and a rather under-burdened development staff, documentation usually just can’t get the attention it needs to be truly up-to-date and complete enough to be valuable.
In my experience, the best solution to this conundrum is automation and process integration.
Documentation automation is all about delivering documentation based on the original design artifacts and not as an independent copy. In BI, this means direct delivery of the data dictionary from the modeling tool via a repeatable, no-touch technical process. It mean that source to target mappings are captured in a way that allows them to be directly included in technical design specs and technical user documentation. And, it means that diagrams, flowcharts, and mockups are created in such a way that they can be used during refactoring without having to start from scratch each time.
Process integration takes these tool capabilities and applies them to the development process, combing design and documentation steps. This means that designs are communicated through documents, that tests evaluate technical components against these documents, and that the entire process is driven through a collaborative, document driven process. Even for iterative development. Note that I made no comment on how much documentation is produced, and I’d advocate for the minimum needed to communicate the design to those tasked with development, testing, and operation of the system.
To make all this happen, teams have to break free of the MS Office based processes they’ve used since day one. Word documents (at least on their own) simply can’t meet these needs, and collaborative creation, editing, review, and maintenance of stand-alone documents are the primary reasons why documentation is often neglected.
Here’s what we need:
- Easy to use.
- Available to everyone on the team (almost certainly browser based).
- Supports collaborative editing.
- Supports automation, e.g. reporting from metadata, from logs, from the warehouse itself, etc.
- Supports writing and drawing, and maybe audio, video, and screen capture.
- Integration with development and deployment management tools.
Fortunately, none of this is outside the realm of normal in the Web 2.0 world. The first three are pretty much the description of a wiki, so that’s a good start. Most wikis support plugins, so getting external data in shouldn’t be a problem. The last two are a little trickier.
In the market, there’s a few natural choices. MediaWiki is pretty much the king of wikis, so that’s a good place to start. It meets most of these out of the box and there are some drawing plugins that at least partially meet the drawing and diagramming requirement. Support is a little tough, but it’s a very active community, so that shouldn’t deter, and free (at least for the software) is always nice.
On the commercial side, anyone with a SharePoint installation should certainly look closely there. SharePoint has the added benefit of a huge content and document management capability. There are also many, many ways to integrate SharePoint with other tools including Team Foundation Server (TFS) if that’s in your toolbelt. The biggest drawbacks here are the cost and complexity of the platform and the fact that you’re going to be really tempted to get back into old habits with MS Office since you’ll need to use Office for some of the functionality, especially Visio.
My pick this arena is again in the Atlassian suite with their Confluence wiki. Confluence is designed as a business oriented wiki and can be paired with arguably the best wiki drawing tools on the market in Gliffy and Balsamiq mockups. Confluence is very well integrated with JIRA and the other Atlassian tools and can be easily configured to suck in information from around the dev team’s virtual water cooler. The cost is manageable and the support is dedicated without having to rely on open source forums or a more generalized corporate support system.
The universal “best fit for you” rule applies here as always, but I hope I’ve made the case that the status quo probably isn’t working and an innovative approach might be just the ticket to break out of the stale, missing, or uber-expensive documentation cycle.
