The Logical Blog by IconLogic

Project Management: Documentation Maintenance

by Kiranmayee Pamarthy

 

Documentation projects are usually time limited, but the products they create need regular, ongoing attention to work correctly without becoming obsolete.

In many organizations, the project team, which has seen the project through to completion, may continue to have responsibility for the final product post delivery. What is the impact of such maintenance projects on planning documentation activities? And how should the project team approach such documentation maintenance projects? 

We always get to hear or read about how to create documentation from scratch, where we have the freedom and capacity to change anything, and we have little dependency on the technical team. None of these perceptions are true when we deal with documentation maintenance projects. Many times, such projects need to be completed in a very short time. They generally need immediate action, quick revisions, and quality output that satisfies the customer.

We need to realize that documentation is an integral part of the post delivery phase of a project, and keep in mind that we must do the following:

• Be aware that different types of documentation may need to be prepared for different customers of the same product.
• Don't wait to create and maintain documents until after the lack of documentation has hurt the project.
• Closely monitor the post-deliverable phase and plan for subsequent releases.
• Use the IDEAL model: Identify, Diagnose, Establish, Act, and Leverage.

 Maintenance projects can involve any or all of the following:

• adding or removing functionality and content.
• revising the layout, i.e., moving pages or whole sections to a different location in the document.
• reconfiguring the whole product for a particular customer.
• changing an existing functionality.

The documentation maintenance process should be viewed as iterations of any development effort.

Maintenance Release Types

Error correction: correct faults in a delivered system. Documents need to reflect change requests from customers or from the testing group.

Enhancement: improve performance or add new functionality. Document activity needs to begin very early in these types of changes since it will involve planning and deployment of additional resources. This includes roll-forwards from previous maintenance releases.

Mixture: a combination of error correction and enhancement.

Adaptation: adapt the system to a new environment.

The documentation may need to reflect error correction, enhancement, or a mixture of these. It is likely that more time will be spent on enhancement releases than on error corrections. It is always vital to plan the next documentation release so as to maximize the efficiency of resources and also improve quality of the document. Thus, it is very important that the documentation team is involved from the initial phase of maintenance releases.

Project Management: Metrics and Variances

by Kiranmayee Pamarthy

As Tom DeMacro explains in his book, Controlling Software Projects (DeMacro, 1982), "you cannot control what you cannot measure."

The precursors for measuring are 1) Setting the guidelines and standards; 2) Managing the project; 3) Capturing the metrics; and 4) Usability.

Setting the standards. First and foremost, create a style guide or style sheet and use the guide for your standards. Continuous usage and strict adherence to these standards help writers become proficient in delivering quality deliverables. Employing multiple writers should not impact the way your company presents documentation to the customer. How many times have you heard the technical folks (the engineers for example) say that the user manuals are not used, so, why take pains to deliver quality deliverables? Negativity must never stop the quality output.

Managing the project. I'll save this section for a future article.

Capturing the metrics. Metrics can be captured for measuring productivity, defect density, budgeting or cost, etc. The following metrics analysis should be carried out for projects (overall and phase-wise where applicable), and corrective action taken when required. The variances are calculated against revisions:

• Effort Variance % = ((Actual  Effort - Planned Effort) / Planned Effort) * 100
• Schedule Variance % = ((Actual  Duration - Planned Duration) / Planned Duration) * 100
• Size Variance % = ((Actual Size - Planned Size) / Planned Size) * 100
• Review efficiency = No. of review defects / No. of  total  defects  (review + test +post-ship) - defects could be author induced or lack of technical inputs
• Productivity = Size / effort (No. of features or change requests / staff days)
• Defect density per unit size
• Overall Defect Density = Total number of defects / Size
• Pre-ship Defect Density = Pre-ship defects / Size
• Post-ship Defect Density = Post-ship defects / Size
• Productivity Variation
• Productivity Variation = (Actual Productivity - Estimated Productivity) / Estimated Productivity
• Estimated Productivity = Estimated Size/ Estimated Effort  (No. of features or change requests / staff days)
• Actual Productivity = Actual Size/ Actual Effort (No. of features or change requests / Staff days)
• Team Stability Index = Peak Planned Staff / Total number of staff in project
• Delivery Commitment = No. of deliverables delivered on time with regards to latest revised date / Total no. of  deliverables
• Resource Utilization  % =  (Actual project effort logged / Allocated effort) * 100
• Defect Age = Phase (Detected - Attributed)/ Number of Defects
• Cost of Quality (in terms of effort) 
• Prevention cost (Facilitation, Audits and Work Product Inspections)
• Appraisal cost (Work Product Reviews, Independent Unit Testing)
• Failure cost (defect fixing, i.e. rework)
• Requirements stability % =  (Number of requirements identified / (Number of requirements + changes to requirements)) * 100

Usability. The organization can create a set of usability metrics for capturing the data of the usage of the document.