Documents don't have teeth...

I was just told to write a technical specification document. Now I did write the first draft of it and sent it to Vikram. But I was reviewing it myself and was wondering how useful a Tech Spec document is. There are headings like “Description of classes”, “Methods” and screenshots. Now what if the code changes? What if at a later stage we have to re-factor the code? The document is not going to change automatically. And if we don’t manually go and change the document, the document in itself is not going to verify with the code and check if they are in sync. That’s why the metaphor on the subject line. The documentation doesn’t have teeth to bite into the code and test.

Alternative options:

Sandcastle: Documentation compiler for managed class libraries. 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:

1. Works with or without authored comments

2. Supports Generics and .NET Framework 2.0

3. Sandcastle has 2 main components (MrefBuilder and Build Assembler)

4. MrefBuilder generates reflection xml file for Build Assembler

5. Build Assembler includes syntax generation, transformation..etc

6. Sandcastle is used internally to build .Net Framework documentation

Behavior Driven Design: Now this was something I was reading about long back. The idea is quite rough. But we could use BDD and extend it to generate live documentation. A word document is a dead document. It doesn’t change with the code. We could generate some form of documentation that could change with the code or perhaps make sure the code changes in the right direction. BDD ensures that the behavior of the code is consistent beyond code changes and intermittent releases. I am thinking something in that direction.