Executable documentation
It's good to see build and release automation becoming more and more common, but I'm curious to see whether this wave of automation will stop at just releasing or flow over to other areas of software development, and change the attitude in general.
Though automated testing and continuous integration took some time to spread - despite the fact that software developers (who spend their days automating mundane tasks so clients can focus on adding value, and thus should have been easily convinced) have been (and some are still) opposed to the idea of automating the mundane tasks that they perform; I'm hoping that one of my pet peeves - stale documentation - will become more and more extinct as automation becomes more mainstream.
Below are just some document types that could be made live and executable:
- Specifications. I'm not the first to suggest this, acceptance testing, tools, and books have been around, but haven't caught on yet. I've been introduced to this concept by Gojko Adzic, and I can recommend his past talks/videos or books for getting started on this topic.
- New developer getting started instructions. In addition to local machine setup (though the approach Tamas Sipos described of using virtual machines per project is even better than scripting it), this usually includes gaining access to all sorts of different file shares, web services, machines, databases, mapping them to proper local names, and so forth. This is usually presented in the form of list, where you actually copy-paste it into the command line. There is no reason this couldn't be scripted. Mirroring access from an existing developer is sometimes easier than keeping the setup scripts up to date.
- Revoking access from departing developers. This might be more applicable to bigger enterprise environments, but it is just as important as setting up a new developer. Script it.
- Installation instructions, and fixlogs/workarounds for 3rd party applications (or even your own applications). These are the ones that warn you to only ever run this script as a given user. Or from a particular machine. And to execute the following commands, containing a loops and decision branches, written in plain text. And to make SQL calls, send xml/json messages, where you just need to substitue <this> with the current value, etc. Script them, and make reduce the document to a single instruction - execute myFix.sh with the following two parameters.
- Code review guidelines, coding standards. Naming conventions, indentations, method length/complexity, all sorts of other static code analysis (the domain shouldn't call the UI code directly! We shouldn't have commented out code! There should be no Windows Forms controls with Visible = false never ever changed elsewhere to true in the class! etc.) should not be done by hand if can be automated - and there are quite a number of mature tools out there, all extensible, such as StyleCop, FxCop, Checkstyle, FindBugs, xDepend. Focus code reviews on the more important things.
- Data flow diagrams. For the live, production system, you are better off generating this dependency graph from the scheduling tool you use, which makes it surely represent production, as opposed to the manually maintained Visio diagram or similar.
Hope it was inspiring :) Do you know more document types I have missed?
