Blog Archives

Documentation Lock-In

Documentation is important. It’s how all the collective knowledge about a piece of software (or many pieces of software) is recorded and organized for use by those who maintain it. Once you get beyond a couple of developers, documentation becomes not just important, but required – without it, it’s not feasible to keep everyone on the same page.

While you could theoretically decide to keep things bare bones and put all of your documentation in plain text files, most developers aren’t masochistic and opt for something more flexible. Tools abound for creating, editing, generating, and browsing documentation – everything from markdown to wikis to static site generators (and plenty of combinations, too).

Given that documentation becomes a necessity so quickly, a given project often winds up choosing some set of these tools fairly early on in its lifespan. Sometimes it’ll be whatever the current fad is, sometimes it’s the system one of the developers used on an earlier project and liked, sometimes it’s just whatever happened to pop up first on Google. In general, though, such tools are typically chosen with at most only the current needs of the project in mind.

The problematic reality

It’s a common situation that a few years or even just months down the road, the documentation system is no longer really suited to the task at hand. Perhaps it’s missing features that would be extremely useful now that the project has matured, or perhaps folks have discovered that the system they chose is a maintenance nightmare and would rather have something more robust.

The more complex a documentation system is, though, the harder it is to move to something else (while preserving existing knowledge). Even something as simple as links between different documentation pages can present a serious headache: not only do you have to worry about migrating the content of pages from one system to another, you also have to make sure all the links are pointing to the right places. In effect, you wind up writing a compiler+linker combo: a compiler to translate the content of your old documentation system to your new one, and a linker to fix up all the references.

Of course, that’s not even counting any potential mismatches or incompatibilities in the content itself. Perhaps your existing documentation system supported templates in one form, and your new system does too… but in a completely different format. You’ll most likely wind up having to translate all the templates by hand, and then adjust your “compiler” to invoke them in the new format. Alternately, maybe your old system supported JavaScript, and so you have to make a choice between finding a new system that also supports JavaScript (and fixing anything which breaks in the transition), or dumping JavaScript support and either removing or reworking anything that was using it.

All of this makes it a lot more painful to change documentation systems after the fact. It’s not surprising that so many large projects wind up having documentation systems that seem needlessly sub par: it’s probably not because they like them that way, it’s because they’re effectively stuck with them.

Thinking ahead

So what to take away from this? Nothing’s going to make the problem completely go away. As long as useful documentation exists, some of these problems are going to crop up, and getting rid of documentation obviously isn’t the solution. Instead, the best strategy is probably twofold.

First, try to plan for the future as much as possible. If a tool only barely meets your needs now, it’s almost certainly not going to meet them later on down the road. Note that “meeting your needs” can apply to many aspects – not just the raw numbers. In addition to such absolute performance, there’s also things like minor irritations and maintenance hassles. If the system you choose is “good enough” but almost makes you fed up now, chances are you will get fed up with it later. Avoid compromising on the underlying system, because chances are you’re going to be stuck with it for a while. Documentation often gets even less refactoring love than code does (and code often doesn’t get nearly enough).

Second, since knowing the future is often hard (and the services of those who can do it reliably are often priced in souls/hour), plan for change – especially in the early stages of a project. When things are just starting to take off and get a little more complex, hold off on adopting a giant flashy feature-rich documentation system. Keep things simple instead: rich in information, light on complexity. Avoiding complex features will make migration into another system a lot easier down the line, once you get a better sense of where the project is headed and what its documentation needs will be.

Bonus tip: for web-based documentation, use an editable URL shortener for external links into the documentation. When you change documentation systems, the URLs for pages are likely to change at least a bit, breaking external links. If external sources use the shorturls, though, you can just update where those shorturls point. It’s a lot easier to update a bunch of shorturls in a database you control than it is to try to get everyone else to update their links.