Why Technical Documents Make For Better Software
In any software project, documentation will play a part. Typically it will consist of a set of requirements, technical documentation of the architecture, technical documentation of the source code & user documentation, e.g. help files.
Usually the set of requirements will be made, software written, and enough instruction given to users for them to benefit from the end product.
Occasionally, the technical documentation in a project can be an afterthought, sparse or even non-existent. This is unfortunate as technical documentation can bring varied and worthwhile benefits.
GOOD PRACTICE
Good technical documentation should consist typically of architecture (database layout, physical layout, network diagrams), UML diagrams & explanations of trickier parts of the code and/or tutorials. There shouldn’t be any need to document the inner workings of each class and function beyond code commenting. Automated documentation tools, e.g. Doxygen, Javadoc etc. can be used to create reference documentation from the source code and comments.
Always include things that may seem obvious to current developers but not to people coming from outside, e.g. project access – where is the source code repository held? Where is the development environment and on which servers? What are the production environment requirements, e.g. OS, available programming languages, libraries, hardware & database types? These are things which will take a short amount of time to write but aid greatly in visibility to staff (future & present) and management of the company.
As time goes on in a software project the technical documents themselves, if created, will become out of date. A method should be found of updating documents to keep them relevant. Auto generating documentation tools like Doxygen can simply be run periodically to remain current but don’t forget to maintain the architecture documentation, e.g. database diagrams and network layouts if changes are made there.
Programmers want to program, but they should produce documentation too although it can hardly be described as fun. So where will the motivation come from? The answer is that the motivation and recognition of the need for it has to come from the company management level. It needs to be a part of the company ethos as documentation is at its heart a collaborative exercise. Without that, proper documentation may not get produced, be incomplete or be of poor quality.
FOR & AGAINST
In an environment where good documentation is available and complete, it provides visibility to those that need to make decisions on future development and allocation of time & resources. It is always much nicer to work on a well documented system, rather than having to work backwards from a user level fault in the product, identifying the bits of code and then ‘grepping’ through the whole source tree to find all the other relevant and related parts to make corrections. Without it decisions on maintenance and product improvements can be very difficult to gauge and lead to rewrites or projects being scrapped – at which point morale and motivation in a development team can begin to fracture, affecting the other parts of an organisation.
A development environment where developers are aware their work will be documented in some manner can lead to a higher, more re-usable quality of code produced. The documentation process itself can uncover problems/bugs which can at least be documented, giving awareness of a problem to the company before users experience the fault. As the problem is documented it will more easily be corrected.
There’s no denying it, documentation comes at a cost. It will require, time and resources of development staff who are already familiar with the implemented architecture and source code. There may be a reluctance from the company to invest that resource. After all, they’ve got a working product for which they have customers who should not be overly concerned with dry explanations of APIs & database schemas. However, consider then the costs of absence of documentation as the time comes to extend, or make corrections to those APIs.
Will the original developers still be around? Will new staff have to spend lengthy periods (at company expense) understanding the project before being able to make changes? In time the savings will outweigh the cost. Resource allocated to documentation can be considered an investment in the future.
Happy documenting*.
Author: Kevin Smith
*I cannot believe I just said that!
