Documentation is Modeling

I've had the opportunity to discuss the value of documentation as a part of the software creation process lately. I hadn't noticed until then how much my views were influenced by a couple of pages in Agile Principles, Patterns, and Practices in C# by Robert and Micah Martin. The book is absolutely phenomenal and has had a strong influence on my development in the last few years. There's a small transition between two sections of the book as it leads out of principles and into modeling practices. That transition struck a cord with me in regards to documentation and that cord is resonating loudly as of late.



Modeling
A bridge builder creates a model to test the strength to weight ratio of the bridge. An airplane designer creates a model to put it in the wind tunnel to test the aerodynamics of the design. The bridge and airplane models were smaller versions of the real thing built to learn something about how to better build the real thing. Why smaller? Smaller is cheaper in these cases. An important aspect of modeling is that the model is cheaper to build than the real thing. If the model is more expensive to build than the real thing it wouldn't be providing any strategic value, you could just skip building the model and go straight to building the real thing. The second value in the bridge and airplane models is that they were built to be tested. One was tested by how much weight it could hold, one was tested to see how efficiently it could move through the air. Without being tested the models provide no value, they're just like the model car kits I put together as a kid, they're fun to look at but not good for anything else. Without testing the model you don't learn anything about building the real thing.



Value from Modeling
Modeling provides value only when both of the following are true. Without both being true modeling is just wasted work to create something pretty to put on a shelve and admire.

1. The model is cheaper to build than the real thing.


2. The model is built to be tested to figure out how to build a better real thing.

Modeling Software
Software is no different from the bridge or aerospace industries in regards to modeling. We model software by writing something down on a piece of paper, whiteboard, or napkin to express the characteristics and designs of the real thing. We then test that model by asking our peers, customers and other knowledgeable people if their assumptions, scenarios, goals, etc are all fulfilled by the model. Their answers determine how much the real thing will reflect the model, or if remodeling needs to be done. Modeling in software takes many forms, UML, requirements documents, technical specifications, test cases, use cases, etc. They are however all textual models that can be tested to prove some virtual characteristic of the software.



Value From Documentation
Thus, applying the two points above that determine when modeling is valuable we can determine when to document and how to get the most value out of documentation.

1. Documentation should be relatively cheap.


2. Documentation should be created when we want to test the software before building it.

To get the most from documentation we should only create it when we need to test and when we can create the documentation and test it cheaper than creating and testing the software. I think the key point that is often missed is that the documentation needs to be easily testable. Documentation in thesis form might be a well written masterpiece but it's not easily testable. To figure out if a particular scenario will be fulfilled I would have to read the whole document to find all the references for impacts to that scenario and then compose them into one and apply my scenario test. That is not cheap, nor easy. Modeling software with User Stories however is much easier to test because the model is organized into identifiable pieces of work in the way that the development team builds and tests the software. This results in a shared thought pattern (ahem, mental model) by the entire team - the modelers and the builders. User Stories convey the virtual characteristics in ways that allow for cheaper and easier testing of the documentation in order to build better software.

So, as we create documentation to help us build software we should ask ourselves:

1. Is this documentation testable? (If no - then don't create it.)
2. Can something be learned about the software by testing this documentation? (If no - then don't create it)
3. How can I make this documentation cheaper to build and maintain?
4. How can I make this documentation easier to Test?