The Importance of Executable Documentation

While historically we have tried all kinds of documentation, a general rule we have found is that if the documentation isn't executable, it'll probably be out of date before we launch. What do mean by executable documentation? Something that is readable by business stakeholders and that captures their functional requirements in a way they can comprehend and sign off on, but that can be automagically transformed into a working system. If any human intervention is required to map between the requirements and the application, eventually they'll probably get out of synch.

I should clarify, in some cases the requirements will depend on some hand written code. We typically handle such cases by referencing a method in the documentation that is then hand coded, so the requirement for the method simply includes the appropriate hand written code (whether written specifically for this project or included from a library) into the application. That said as much of the time as possible, we try for the requirements to be generatable or interpretable into working code so that most changes to requirements change the running system in (close to) real time, rather than having to do a re-work cycle as the programmers and DBAs try to modify the app to meet the updated goals by hand.

The challenge we face is finding the right way of documenting and presenting these executable requirements to our target audience who are often small business owners with no IT background. In practice we're moving towards XML as the internal lingua-franca for passing the requirements around, but we're still investigating less verbose formats (including non-textual formats - "boxes and arrows") for displaying them to the clients.

A couple of caveats:
Firstly I'm talking about functional requirements. We don't accept client specific non-functional requirements (lucky us!). Our partners may accept custom CSS/HTML requirements such as browsers to support, but we don't get into that and realistically at the price points we offer, to guarantee latency or number of concurrent users or other non-functional requirements is implausible - the cost to specify and test the non-functional requirements in sufficient detail would probably exceed what we charge for building the entire application. I'm not saying you couldn't come up with DSLs for describing non-functional requirements and heuristics that (if they were sufficiently conservative) would allow you to meet them automagically with configuration decisions being made based on the non-functional requirements statements based on some kind of rules and configuration engine - it just isn't something we need for our use case.

Also, we encourage some non-executable requirements. A short, clear statement of why a system is being built who will use it, and by what metrics success will be determined is a great idea for any non-trivial application. Such "business intent" requirements do (or should) change very infrequently, so I find them to be a useful exception that proves the rule. But once we're getting down to screens, actions, steps, objects, properties, relationships, validations, transformations, data types and the like, those should be described in an executable format.

Any thoughts/experiences with defining executable documentation formats or presenting them to non-technical users?