- The purpose of documentation
- Strategies for making documentation practical
- Knowing when you are in trouble
- Summary
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Knowing when you are in trouble
An organization is in "document trouble" when project team members create documents that have little use or value. This can occur when either the team members are unclear on a document's purpose or when a document is created to satisfy the needs of an external auditor or assessor.
In the first scenario, a committee is typically formed to define a specific phase of the software life cycle. The template is the committee's deliverable. The template is successfully used on a few projects and is then made standard operating procedure. When the template contains more sections than it needs to, and when the larger audience is not trained in the use and purpose of the template, too many project teams "fill out the template," because "they have to," with redundant information. At this point, the resulting document can be viewed as unnecessary documentation, particularly when the information is not regularly used to manage the project.
In the second scenario, project team members believe they have to create additional documentation to prove to an external auditor or assessor that they are managing their project correctly. Memos capturing meeting discussions, Statements of Work documents summarizing product requirements, and design documents that are created after the code has shipped, are produced to "pass the audit." Documentation is viewed by the team as an activity unrelated to building the product. It's a "keep management happy" tax.
In this latter case, the cause can be due to poorly trained auditors who look for "paperwork" but don't really understand the fundamental practice that is desired of the project teams. For example, the auditor looks for a Statement of Work document even though a detailed set of requirements exist covering the same information, or minutes of meetings are examined even though the project is six months behind and none of the corrective actions during those six months have been implemented. Here, the auditor needs education and the documents required of the team need tailoring.
"Pleasing an auditor," can also occur when the project team members have not analyzed why an engineering or management practice (and its associated document) is required and how they could benefit from it. In such cases, the team "reacts" to the process requirement without understanding why the requirement is there. Here, the team needs training on the purpose and correct use of each specific document.
If the project is performing the required practices correctly, and if the required practices have been well thought out and tested, the natural documents produced should be essential for team operation and be adequate for any auditor or assessor to see how the project is being managed. The goal is "no extra paper work."