- 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
Strategies for making documentation practical
Focusing on the organization's needs
Answer the following questions to determine the organization's needs for each document:
What goal are you trying to achieve? What role does this document play with respect to this goal?
What problem (or need) are you trying to solve with this document?
These questions focus you on the specific purpose of each document. Your responses scope the document and provide you with an end point (so that you don't go on and on "Filling out the template!")
In one group we observed that 50% of each requirements document contained information describing how the product was going to be built, instead of focusing on what the product was going to do for the end user. The lack of a clear goal allowed the specification to become a "catchall" document with no end point. An example goal for a requirements document is, "Capture the needs of our customers by defining the tasks they need to perform and expectations they must have met in the solution we deliver (i.e., performance and reliability targets)."
Merge duplicate work products
When project documents contain similar information, merge them together. For example, if there are three documents to complete: "Statement of Work," "Product Requirements," and "Contractual Requirements," and each will contain the same information, write one document and define the information one time. In the document, cross-reference the other two templates that this document satisfies. If there are differences in the three documents, but considerable overlap, write one set of requirements, label those items that are "Statement of Work" deliverables, and those that are "Contractual Requirements."
If you are using the SEI CMM1, merge work products together to implement specific practices. For example, a Software Configuration Management (SCM) plan, Software Quality Assurance (SQA) plan and Software Develop-ment Plan (SDP) can be merged. Milestones and activities for SCM and SQA might be listed on the master schedule in the SDP.
Remove redundancy in templates
Closely examine sections that are redundant in your templates. The template might have looked sound when first created, but during use you might find that some of the sections contain the same information. Each use of the template is an opportunity to put the template "on a diet" and delete redundant sections. For example, the requirements template in Figure 1a can be slimmed down to the template in Figure 1b when we realize that everything said in sections 1 and 4 have already been said in sections 2 and 3.
)
Figures 1a and 1b. Redundant template sections are removed.
Process documents also suffer from a lack of purpose clarity. For example, suppose you are using the SEI CMM and have been chartered to develop a process for creating project schedules (Software Project Planning activity 12). You might be tempted to build the world's greatest and most comprehensive schedule creation process, with all known "bells and whistles." In the document one could regurgitate the CMM text, include references to 15 books on the subject, and refer to "Critical Chain Analysis," (whatever that is!). The appendix could include three pages of cross-references to other models and standards.
Alternatively, ask the first question and you might decide that the goal is to determine which product features can be complete by the established delivery deadlines given the available resources. This process describes how to develop a schedule to help achieve that goal.
The second question would bring out the problem(s) you want to solve. An example is to prevent your project from chronically over-committing, causing financial loss to the company. Now write a small process to accomplish these two items. An example is shown in Figure 2.
)
Figure 2. A schedule creation process.
When do you stop defining this process? When your goal has been achieved (e.g., scoping the project) and your problem solved (e.g., avoiding over-commitment). Refine the document further when it no longer meets the need.
Don't have separate audit checklists that repeat the original process. Use the original process as the checklist
If you have a process assurance function that audits projects for process compliance, use the process descriptions that the projects use; don't write a separate audit checklist. Write processes (for example, estimation, schedule creation and change control) in a style that can be used for both project and audit purposes. It might be necessary to provide auditors with some additional guidance in conducting the audit and reporting the results, but it is unnecessary to duplicate the same process information in a different format.
Consider one representation
Write processes using one representation. For example, if you are creating a process for risk management, it would be redundant to have one file of presentation slides, the same process formatted using a word processor, a version in html for browsing, and the same information again using a flow diagramming tool.
Instead, determine how the process document will be used (e.g., online use by developers during project execution, or in a classroom setting with 100 people being trained). Then consider one representation that can suit all needs. For example, a presentation slide format can be printed for reading, e-mailed for sharing, presented for teaching and uploaded for browsing.
Always consider one page (small) for each process or sub-process
There are approximately 60 lines on a page and 10 words per line. That is quite a lot of information. So consider keeping process documentation to one or two pages (at least at the beginning).
How do you keep processes to one or two pages? By limiting how much detail you allow yourself to write. Unless you plan on writing forever, you have to put some limit on the document, so start with one page. When you are tempted to add more explanation and detail, refine what you have defined, don't necessarily add more sections.
A "Documented Procedure" can be the instructions embedded in a work product template
Organizations using process improvement frameworks, such as the SEI CMM and ISO9001, might be tempted to write procedures "because the framework states that they are needed." Procedure creation is often followed by creating a template to assist the procedure user (for example, a template for an SCM, SQA or project plan). Creating both a procedure and template can lead to redundancy.
An alternative approach is to imbed the instructions for completing a template in the template itself. The procedure and the template are the same document. For example, the practice in the CMM, "Create an SCM project plan according to a documented procedure," can be implemented by developing a lightweight template with imbedded instructions for use (see Figure 3).
)
Figure 3. Procedure for creating an SCM plan combined with an SCMplan
template.