Documentation is essential for any computer system. It doesn’t matter if you are purchasing a product off the shelf, or write custom software. There are many decisions that have been made to make the software and hardware work. Those decisions are best maintained when the appropriate level of documentation is created and maintained.
If you have followed me for any period of time, you probably know I am not a proponent of lots of documentation. I prefer to find as many ways to reduce documentation as possible. If you can document requirements in the form of automated unit tests, you reduce the number of documents you must maintain that produce no actual code. Still, there is a lot of documentation that may not be readily understood or tested through code.
Network, or database diagrams are a good example of valuable documentation that cannot be replaced by unit tests. Even if you have micro-systems loosely coupled, there may still be benefit of UML type diagrams for sequence, data flow, use cases, interfaces/classes, packaging, etc.
I brought this up with the thought that documentation can benefit from version control, and as such, has value if it is versioned like the tools implementing it. What prompted me to this topic was a post from the Brent Ozare newsletter pointing to the GitBook repository. This is a really interesting tool combining modern writing with version control. We have similar things for some other systems. But, the versions tend to only lend themselves to binary comparison between versions. That’s something of lesser value.
GitBook documents are written using markdown or AsciiDoc, which being text based may be compared from one version to the next. This isn’t much different than a wiki engine, using simplified tags. The value is that there are converters from these formats to HTML for web page creation, or other document formats. So, you get all in one. The neat part is that you don’t have to learn a new syntax to use it. There are editors supporting the file formats, providing you with a wysiwyg editing experience.
The downside of this tool is that the version control is not synchronized with your application. However, if that isn’t a requirement, perhaps something like this is for you. It isn’t free for businesses, and may be cost prohibitive. Something to look into.
What’s your position on documentation? Do you do it? Do you maintain it? Do you version it? Share your experience in a comment.
Cheers,
Ben