There is always the need for good documentation if a system or API lacks intuitive handling. For simple tasks this should never be the case, but to accomplish more complex tasks this is often necessary. Documentation is not only the printed manual, it is also context sensitive help that leads to an information system with additional advice for the task at hand. In whatever form the documentation is presented, there are some common attributes a good documentation requires. Two of them are correctness and being up-to-date. Let’s focus on the need of documentation for a software product being up-to-date with the implementation, since being out-of-date implies that the information is no longer correct. How can this be accomplished?
Living Documentation
One answer is given by Gojko Adzic in his book Specification by Example: Living Documentation. What is living documentation?
Living documentation is a source of information about system functionality that’s as reliable as programming language code but much easier to access and understand.
Gojko Adzic
Behavior Driven Development Tools
That opens a wide spectrum of technologies. One set of tools are found in the world of behavior driven development (BDD) (for more information on BDD please refer to “Introducing BDD” by Dan North), e.g. Cucumber or JBehave (please refer to Resources on the Specification by Example’s website for a list of additional tools). These tools make specifications executable and allow to gain more transparency on what the code does compared to what it was designed to do. If there is a discrepancy, these tools will tell immediately.
Reports
But BDD tools are not the only utilities that support living documentation. Gojko Adzic names one problem in today’s software development process that is addressed by the living documentation approach:
Code is often the only thing we can really trust; most written documentation is outdated before the project is delivered. Gojko Adzic
Robert C. Martin states another in his book Clean Code:
The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong.
Robert C. Martin
And he comes to the conclusion:
Comments are, at best, a necessary evil.
Robert C. Martin
We argue that a comment is a form of documentation that relates to an implementation detail. So we can rephrase the cites of Robert C. Martin to:
The older a documentation is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong.
Documentation is, at best, a necessary evil.
This is true for everyday’s devices like mobile phones. A documentation delivered with the device may be out of date after the first software update and as a user we do not want to have to consult a manual prior to enjoying its services. This is also true for software documentation. A document, especially written with a tool designed for creating slides or letters, will loose its benefit over time (as the burden of maintaining the document consumes scarce resources and details may evade the maintainer’s eye) until it does more harm than good (at the time it is out of date and its information is no longer correct). It would be honest to admit that such a document is created only to preserve a snapshot on information about the software, as soon as the burden of maintenance is greater than its benefit as a source of correct information.
Generating Reports
The cites of Gojko Adzic and Robert C. Martin direct us to the conclusion that we want our documentation to be as minimal and as next to the code as possible. Therefore it is useful to create reports that make the information in the code more accessible and easier to understand. We have released a set of tools that do exactly this (and are continuously working on the improvement of these tools):
- smartics-testdoc-tools – visualization of tests as stories, similar to the goals of agiledox, written by Chris Stevenson back in 2003.
- smartics Properties – provides a library to use properties and generate a documentation within a Maven project site.
- smartics Exceptions – provides a library to use exceptions and document the meaning of exception codes.
These projects have in common that they analyse (test and production) code and generate reports. They help to synchronize the implementation with the documentation at no additional cost (besides configuration of the tools and adding a few metadata to the code). If the code is changed, the documentation is updated automatically. The tools allow developers to comment their work and make this documentation also visible to non-coders. For many projects this information is enough. For projects having requirements such as multilingual documentation or documentation that is written by a technical writer, these reports can be used as a foundation for this additional work.
Screenshots of Reports
Here is an example on a testdoc report generated by smartics-testdoc-tools:
This an example of a report on properties generated by smartics Properties:
This an example on a report on exception codes generated by smartics Exceptions:
If you are interested how to use these tools in your project, please consult the project’s sites:
| Project | Short Description |
|---|---|
| This project provides tools to generate documentation from tests written in Java. Currently the tools concentrate on making the story behind tests visible. They use the tests to generate a documentation from executable code. Since the test code itself is documentation, we talk about executable documentation. |
| smartics-properties is a library for Java to declare and define properties and to access them from an application in a convenient way. Convenience means that properties are easily
There is also a plugin to generate properties reports with Maven. |
| This project provides Java libraries to make exception handling in applications easier. The following services commonly required for application, be them standalone or distributed multi-tier enterprise applications, are addressed:
|
