Documentation, it’s a boring job, but someone has to do it, right? That’s what process advocates say, but maybe that view is overstated. To think about that question, consider the reasons and flaws of documentation. On the plus side, it’s hard to argue documentation is bad; it’s additional data. In theory, documentation helps others understand something non-intuitive. Managers hope documentation will allow replacement of one employee with another. They say in case of accident (“hit by a bus”), but we know the reason is in case one employee quits or demands more money. In another case, it educates users, and reduces the need for hands on training.
Documentation doesn’t always live up to those goals, but it at least partially accomplishes them. But I see two primary problems with over-documentation. The first, it is better not to need documentation, then to have it. A goal of 100% documentation not only distracts from the quest to reduce it’s need, but as I’ll explain, it’s often an obstruction as well. The second problem, is time. Creating, maintaining, organizing and disseminating documentation is time consuming.
The second problem is obvious, and there is little to be said. Each project must make it’s own decisions on when and how much documentation is appropriate. Whatever that decision is, insure the entire lifecycle of documentation cost is considered.
The idea of fulfilling the goals of documentation through intuitive design is much more interesting. It’s a commonly accepted practice in the development world that the design of classes, method names and other elements of code should strive to not need documentation.
If you have the choices of creating a method void Execute(byte[] array, string input), and then providing documentation stating, “The Execute(ref byte[] array, string input) method reads the contents of a file with the input path input into a byte array, array.”, or simply creating a method byte[] ReadFromFile(string filePath) with no documentation, any rational developer would choose the second.
It’s not impossible to do both, especially in the case above, but it can be difficult. I already pointed out it’s time consuming, but documenting what doesn’t require documenting is most tedious. Repetition is the fuel of tedium, so don’t repeat yourself.
It’s not just code that benefits from the rule of eliminating the need for documentation. The highest goal of any user interface designer should be an application that is intuitive, an application that trains the user through use. RTFM is a nice phrase, but it’s been repeated so many times we should question it’s wisdom.
0 Responses to “When (not) to document?”