Software documentation: Do it right
If we know the value of documentation, then why don't we use it more often? For starters, most software documentation suffers from many of the following issues:
The primary reason such issues exist is because software documentation is often considered a secondary priority. Project budgets are forced to prioritise spending on primary activities involved in the development effort, where management can easily measure the benefits. Cost-justifying documentation efforts are usually subjective and are commonly characterised as cost avoidance rather than generating an ROI. Many project managers view documentation beyond what is minimally required by the customer as "gold plating."
Another source of trouble for software documentation involves the author. Many application development managers feel that software documentation is a standard part of the development effort and, hence, require their developers to produce it along with their coding efforts.
While this is noble in theory, it doesn't take into account the developer's capabilities as a document author. Simply put, technical people are trained to develop and not to write. To address this issue, many application development managers attempt to improve the quality of their software documentation by employing technical writers or business analysts. This presents the opposite problem: Technical writers and business analysts usually have limited technical skills.
The solution depends on the documentation in question and the documentation's intended audience. The general rule is that writing documentation requires a teamwork approach, which allows the developer and the writer to utilise their strengths. For example, if the intended audience is system designers, then the developer should provide detailed input but allow the technical writer to organise and edit the content for grammar.
Regardless of the intended audience or chosen author, the quality of a documentation artifact relates to its usability, which you can measure with these six attributes:
The primary goal behind software documentation is to communicate a system's technical elements and usage. The secondary goal of documentation is to provide a written record of the requirements, decisions, actions, roles, and responsibilities of a development effort. Only when you realise both goals will a given document provide meaningful information.
Scott Withrow has more than 20 years of IT experience, including IT management, Web development management, and internal consulting application analysis.