This morning I was reading Scott Ambler's excellent article on Single Source Information, which references Brad Appleton's Locality of Reference Documentation (LoRD) article. In a nutshell LoRD states that:
The likelihood of keeping all or part of a software artifact consistent with any corresponding text that describes it, is inversely proportional to the square of the cognitive distance between them.
In other words, if the code is over here and the documentation is over there then the likelihood of keeping them in sync is low. For this reason its best to keep the documentation close to the code. Ideally, the documentation should be in the source code file. This is why both Java and .NET support inline XML documentation comments in source code files. Javadoc and NDoc are both utilities that format these XML documentation comments into help files. Since these XML comments are embedded in the source code file, right next to the classes, methods, properties and events that they describe, the cognitive distance is zero. When a developer changes any of these items, the documentation comments are right there - in the very same spot - ready to be updated as well. It just doesn't get much easier.
Shortly after re-reading these articles, and while the thoughts were still swirling around in my mind, I stumbled across the next generation documentation tool: Sandcastle. According to the overview on the download page:
Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:
- Works with or without authored comments
- Supports Generics and .NET Framework 2.0
- Sandcastle has 2 main components (MrefBuilder and Build Assembler)
- MrefBuilder generates reflection xml file for Build Assembler
- Build Assembler includes syntax generation, transformation..etc
- Sandcastle is used internally to build .Net Framework documentation
Wow! Now this sounds like a really useful utility that makes the cognitive distance between code and documentation as close to zero as possible. The beauty of this utility is that it automatically documents the structure of the code, and it also documents intent to the extent that names are descriptives. Now, if your dev team does a good job of keeping the the XML comments in the source code relevant, than this utility automatically documents both structure and intent in a clear and concise manner, while keeping the cognitive distance at zero.
Taking the whole thing one step further, Mike Diehl blogs on how to incorporate Sandcastle into an MSBUILD process. Once you have this up and running, keeping documentation current and relevant just doesn't get any easier!