 |
|||
|
Sample Pages |
|||
|
|||
|
TEMPLATE
FOR A SOFTWARE DOCUMENTATION MANAGEMENT
PLAN Version 2 Software life cycle processes, Clause 6.3.6 Information Management Process |
|||
Purpose
of this Template
This template provides guidance for developing a Software Documentation Management Plan to address documentation issues and satisfies ISO/IEC 12207:2008, Software life cycle processes (2008) Clause 6.3.6 Information Management Process
A Plan is an assessment of everything related to documentation for a project and provides a solid foundation for the project.
The Plan needs to contain enough information to ensure its persuasiveness, e.g., goal orientation, clearly understood figures and tables, and team orientation.
A Plan should be the first project artifact developed since it drives the format, style and documentation processes for all documentation. A contract may not require a Plan, but without a Plan other documentation will have quality and consistency risks and problems that will add cost, time and resources, plus customer concerns about the entity’s ability to produce products and to meet expectations.
There is a saying that, “The job is not done until the paperwork is finished”. This is especially true when dealing with government, or large and complex projects. Paperwork is essential in these situations to provide customers with assurance that the final product is being built right (as required), and the final product is what the customer wants (as expected). Another reason for paperwork is to ensure that only approved changes are implemented into the products.
How
to Use this Documentation Plan Template
This template is designed to aid a person with limited knowledge of documentation requirements and methods to implement a sound Plan. The provided template may be applied to manual and electronic methods and can be easily managed by one person. It is applicable to small, large, critical and non-critical projects. There may be one or more intermediate and final documents.
To use this template, the user
must understand the following:
This template is designed for projects: an
activity that has a defined beginning and end.
However, this template can easily be modified for non-projects.
| h | This
template is designed for projects: an activity that has a defined
beginning and end.
However, this template can easily be modified for non-projects |
| h | This
template’s coversheet and the entire Overview Section need to be
deleted for the final Plan |
| h | Delete
the underlined text, which provides information about how to
use/implement this template |
| h | Italic
text provides optional information (i.e., two or more suggestions) that
may be deleted or used (after changing the italics to regular
characters) to replace other information |
| h | Text
that is not underlined or italicized denotes the recommended wording.
As needed, this text can be modified or deleted to satisfy
project requirements.
Instead of providing examples, this technique makes the template
easier to use by providing users with ideas on how to word the Plan |
| h | If
a temple’s section is not needed, the section can be deleted, or
include the header with a statement explaining the reason for the
deletion, e.g., Not required by the contract. |
| h | This
template assumes the user has a standard format for documents, e.g.,
covers, table of contents, headers, footers, style and format (e.g.,
font, margins, justification and spacing between paragraphs).
If required, the user may add a Preface, Forward or Index
sections |
Support
The publisher provides
three (3) hours of free consulting with this product concerning the
understanding and application of this template, to be provided within 60
calendar days of purchase.
(Template)
SOFTWARE DOCUMENTATION
MANAGEMENT
PLAN
Version X.Y
Produced for:
Project Name and any other needed information
Security Classification ______
Produced by:
Company name
Address
Telephone: (XXX) XXX-XXXX, Ext XXXXX
E-mail: XXXX@XXXX.XXX
Web page: www.XXXXX.XXX
| 1 | Documentation Plan Scope ...................................................................... | 4 | |
| 2 | Documentation Plan Objective ................................................................ | 4 | |
| 3 | Documentation Plan Purpose ................................................................. | 4 | |
| 4 | Documentation Plan Overview ................................................................ | 6 | |
| 5 | Documentation Management Policy ...................................................... | 6 | |
| 6 | Documentation Assumptions, Constraints, Risks and Dependencies | 6 | |
| 7 | Managed Plans, Documents and Records for this Project .................. | 7 | |
| 7.1 | Managed Project Plans ............................................................................ | 9 | |
| 7.2 | Managed Project Documents .................................................................. | 37 | |
| 7.3 | Managed Project Records ....................................................................... | 61 | |
| 8 | Documentation Processes ....................................................................... | 85 | |
| 8.01 | Identify Documentation Required by the Project .................................... | 87 | |
| 8.02 | Identify Authors ......................................................................................... | 87 | |
| 8.03 | Identify Users ............................................................................................ | 87 | |
| 8.04 | Identify Sources for Data ......................................................................... | 88 | |
| 8.05 | Documentation Design and Development Process ........................... | 89 | |
| 8.06 | Documentation Testing and Verification ............................................... | 89 | |
| 8.07 | Documentation Approval ....................................................................... | 90 | |
| 8.08 | Documentation Production ................................................................. | 90 | |
| 8.09 | Documentation Storage ......................................................................... | 90 | |
| 8.10 | Documentation Maintenance ................................................................ | 91 | |
| 9 | Documentation Management Tools and Aids .................................... | 94 | |
| 10 | Documentation Management Organization and Key Personnel | 94 | |
| 10.1 | Documentation Management Organization .......................................... | 94 | |
| 10.2 | Documentation Management Key Personnel ..................................... | 95 | |
| 11 | Documentation Management Schedule ............................................... | 95 | |
| 11.1 | Development Phase ................................................................................ | 96 | |
| 11.2 | Implementation Phase ............................................................................. | 96 | |
| 12 | Documentation Management Budget .................................................... | 96 | |
| 13 | Amendment History for this Documentation Plan .................................. | 97 | |
| Appendix A - References ................................................................................................. | 98 | ||
| Appendix B - Definitions and Abbreviations .................................................................. | 99 | ||
LIST OF FIGURES |
|||
| Figure 1: Project’s Documentation Process ......................................................... | 89 | ||
| Figure 2: Company Organization As It Relates to this Plan .................................................... | 94 | ||
| Figure 3: Documentation Management Organization within the Project .................... | 95 | ||
LIST OF TABLES |
|||
| Table 1: Managed Project Plans ..................................................................................... | 9 | ||
| Table 2: Managed Project Documents ......................................................................... | 37 | ||
| Table 3: Managed Project Records .............................................................................. | 61 | ||
| Table 4: Documentation Management Processes ..................................................... | 87 | ||
| Table 5: Documentation Identification ......................................................................... | 92 | ||
| Table 6: Documentation Management Roles and Responsibilities .......................... | 92 | ||
| Table 7: Documentation Management Tools, Aids and Their Purpose ..................... | 94 | ||
| 1. Documentation Plan Scope | |||
| This
Software Documentation Plan (i.e., Plan) was developed for Project XYZ
and complies with company requirements for software documentation
management. NOTE:
“plan” (small “p”) refers to other plans. This section identifies the policy; objective; purpose; assumptions, constraints, risks and dependencies; and overview of this Plan. This section identifies for this Plan’s users the extent and limitations of the documentation management methodology and must contain a clear, concise description of the documentation management methodology. It is critical for readers of this Plan to clearly understand the terminology and methodology used. This Plan must fit in with any other plans, e.g., Configuration Management and Project Management Plans. Prior to, or as part of, writing this Plan, a set of clearly defined processes must be established. As defined later, it is recommended that this Plan make reference to these processes (rather than include them in this Plan) and provide a summary of the key processes. This is to minimize changes to this Plan if any process changes. Thus, try to be as comprehensive as possible, but some detailed information is better presented in a Reference Section/Appendix or made part of the referenced processes used to implement this Plan. This Plan may be updated due to a change in planning, e.g., managed documentation or tools. As with any documentation, changes to this Plan follow the documentation change control process described in this Plan. The approved review results are documented in the Amendment History Section. As much as possible, figures and tables are used to provide documentation management information to help in the maintenance of this Plan. |
|||
| 2.
Documentation
Plan Objective |
|||
| This Plan defines
the required project documentation and the processes, resources,
schedule, etc., needed to produce this Plan’s identified documentation
(see the Managed Plans, Documents and Reports for this Project Section),
including change control and documentation maintenance.
This Plan contains all the material or references needed for a
person to understand the Project’s documentation management
methodology. This Plan’s
contents are based on user and Project requirements, standards and
expectations. As the
Project evolves, this Plan is evaluated by the Documentation Manager for
consistency with Project changes and to ensure consistency with other
Project plans. This plan emphasizes the users’ needs, and ensures the Plan’s objectives and purpose are consistent and complement Project requirements and other Project plans. |
|||
| 3. Documentation Plan Purpose | |||
| This Plan satisfies ISO/IEC 12207:2008, Software life cycle processes (2008) Clause 6.3.6 Information Management Process. This Plan identifies and describes: | |||
| a. | What is managed, i.e., the software documentation under configuration control of this Plan. | ||
| b. | a. How to manage this controlled documentation, i.e., high-level description of the main processes and tools. References are given for process details. | ||
| c. | Documentation management roles and responsibilities. | ||
| d, | When
key documentation milestones and activities occur |
||
| For
this Plan, the term “product” includes all documentation prepared
for delivery to a customer (e.g., hardcopies (paper) and electronic
copies, and the final product) and documentation used internally (by the
developing or maintaining organization) to build a user product. Even for small projects, documenting what was done, is being done, or how to operate products, is not always completed in a timely or in a useful manner. A major exception is Off-the-Shelf-Software (OTS) products that require sophisticated (electronic) explanation on how to use the OTS product; a must to sell the product to people with little or no experience with the product. When producers of OTS products work on a complex or large project, many times they find the user asking for documentation the producers have no experience in producing, e.g., detailed designs, requirement trace abilities and plans. Another major concern is documentation change control. History has shown producers provide change control (even if weakly done) for the initial software products, but documentation changes are often after the fact and are poorly implemented. For instance, the template author has witnessed a situation in which engineers modified old, approved documentation amendment history information without going through any change-control process; even though the producing company said they implemented and enforced a change-control process. One of the major problems this Plan will assist a project with is the minimization of review cycles. Each unplanned review increases cost, can greatly impact schedules, ties up valuable resources and impacts team morale. The management of this Plan may only require one person. The key is the development of quality documentation with the help of the entire Project team, not just the documentation management group. This Plan describes the processes used to manage the identified documentation, including the development, maintenance and retirement of this documentation. This Plan takes precedence over any documentation, process, etc., dealing with documentation management that may affect this Project. This Plan consolidates the methodology, requirements and processes used to manage the development, packaging, delivery and maintenance of documentation, including documentation change control. As a result, the documentation management methodology is organized to provide proper control of information development, dissemination, changes and retirement. This Plan provides management with visibility on documentation status and cost; including a clear picture of future documentation management needs. This Plan helps control documentation scope creep and documentation expectations. For this Plan, the term “documentation” includes processes, delivered documentation, any data placed under documentation management control, and the internal documentation used to help produce delivered documentation, or used to manage the Project. The term “management” is used since this Plan includes how to manage and develop useful documentation while maintaining a system for uniquely identifying the documentation and related changes. At the same time, the Documentation Manager manages the related resources and schedules. This Plan addresses the documentation that is covered. It is critical that a Plan delineate what will not be covered, e.g., the change control process may use the Configuration Management change control process or some documentation may not be controlled by Documentation Management. Consideration must be given to factors affecting how to go about working on a project, any specific concerns needing to be addressed for the stakeholders (e.g., users, management and Project sponsor) and what is needed to make the documentation useful. |
|||
| 4. Documentation Plan Overview | |||
| Identify
the major sections of this Plan and briefly describe the purpose of each
major section. Ensure the
identified sections are listed in the same order as presented in this
Plan. The developers of this Plan worked closely with the customers and developers of other Project plans to ensure consistency of terms, schedule, use of resources and content. This Plan is divided into the following major sections: |
|||
| h | Documentation Management Scope | ||
| h | Documentation Plan Objectives | ||
| h | Documentation Plan Purpose | ||
| h | Documentation Plan Overview | ||
| h | Documentation Management Policy | ||
| h | Documentation Assumptions, Constraints, Risk and Dependencies | ||
| h | Managed Plans, Documents and Records for this Project: this Plan addresses covered items | ||
| h | Documentation Processes: a list and summary of key documentation processes | ||
| h | Documentation Management Tools and Aids: list of the key tools and aids used to create, manage and maintain documentation, along with a brief description of each tool or aid | ||
| h | Documentation Management Organization and Key Team Personnel: description of how the company, Project and Documentation Management organizations relate, along with a list of key positions involved with Documentation Management and where they fit within the Project | ||
| h | Documentation Management Schedule: the Documentation Management Schedule is introduced | ||
| h | Documentation Management Budget: a description of the Documentation Management budget and cost accounting system as it applies to documentation | ||
| h | Amendment History for this Documentation Plan: a summary of when and what changes were made to this Plan | ||
| h | Appendix A: References: list of standards and requirements relevant to this Plan | ||
| h | Appendix
B: Definitions and Abbreviations: definition of key terms and a list of
abbreviations and their meaning |
||
| 5. .Documentation Management Policy | |||
|
The
following is the policy for managing documentation:
Insert the company documentation policy here.
This policy should be signed at highest company level as
possible, e.g., Vice President of Product Assurance. |
|||
| h | Be managed, produced and maintained to ensure the highest quality possible | ||
| h | Satisfy
the requirements and defined expectations of the customers and users.” |
||
| 6. Documentation Assumptions, Constraints, Risks and Dependencies | |||
|
This section
identifies perceived documentation problems areas and plans to resolve
the problems. Include what
obstacles users may face in terms of implementing this Plan. |
|||
| h | Over time, customer documentation expectations change. This could impact previously published documentation. | ||
| h | Over
time, product requirements change, thus impacting documentation contents |
||
| The following constraints (application restrictions affecting the Project’s performance) are made: | |||
| h | The user quickly accepts this Plan. | ||
| h | Coordination between the user and the Project team is timely, open and documented. | ||
| h | There are no more than two customer reviews prior to the documentation being published as final and baselined. | ||
| h | The
Documentation Plan and Schedule are updated for the customer’s review
on a schedule set by the Project Manager. |
||
| The following risks have been identified: | |||
| h | Risk: documentation Authors are technically qualified, but do not know how to write readable documentation. Resolution: the Documentation Manager provides writing-training classes, has highly-qualified editors and has established processes and checklists to help authors. The established review cycle emphasizes quality, readability, and content accuracy and consistency | ||
| h | Risk: inconsistency between documentation. Resolution: terms, abbreviations, strategies, figures, tables, etc., are pre-defined, as much as possible. As requirements or information change, this is distributed to all authors, authors’ manager and the Documentation Manager - for distribution to the appropriate Documentation Editor | ||
| h | Risk:
a key Project person is not available (e.g., death or leaving the
Project) to continue the documentation effort.
Resolution: work is
identified through the use of Work Requests (to start a task) and a
recording process, which includes documentation, recommendations,
issues, etc. This allows for new and replacement people to quickly “get
up to speed” on their new assignments |
||
| This Plan has the following dependencies: | |||
| h | Documentation Management Schedule is dependent on the Project Schedule | ||
| h | Project plans depend on each other for consistency and accuracy | ||
| h | Adequate
resources at the scheduled time to ensure documentation stays on
schedule and within budget |
||
| 7. Managed Plans, Documents and Records for this Project | |||
|
Tables 1, 2, and 3
identify the plans, documents and records of this project.
“Managed documentation” is documentation delivered or used by
this Project. Any
documentation not listed in Tables 1, 2, or 3 is not within the scope of
this Plan. As needed, the
Documentation Manager updates this list, which is based on satisfies
ISO/IEC 12207:2008, Software life
cycle processes (2008) Clause 6.3.6 Information Management Process |
|||
| h | General: | ||
|
|||
|
|||
| h | Identifier: enter the Project schema for uniquely identifying each item of documentation. It is recommended that the listed documentation relate to the Project’s Work Breakdown Structure (WBS) | ||
| h | Title: Enter the unique title for each item of documentation. See the notes at the end of the table explaining the genesis of the documentation items | ||
| h | Description and Purpose: provide a brief documentation description and purpose. Do not assume the template provided descriptions are valid for the subject project | ||
| h | Example (specific) contents: An example of what the plan should contain. . Do not assume the template provided contents are valid for the subject project | ||
| h | Phase:
enter the lifecycle phase where the documentation is to be first
baselined. For this
template, the sequence of phases is: concept, planning, requirements
analysis, design, development, testing, implementation, maintenance and
then retirement. Do not
assume the template provided phases are valid for the subject project. |
||
| h | Intended Audience: identifies who is the intended audience of this documentation. Do not assume the template provided groups are valid for the subject project | ||
| h | Prime
Responsible group: identify the group who has the prime responsibility
for the development of this documentation.
Do not assume the template provided groups are valid for the
subject project |
||
| It may be helpful to readers if a “documentation tree” is provided, e.g.: | |||
| h | The Project Management Plan is based on the Project Charter, Contract, schedule, availability of resources, WBS and company processes | ||
| h | All plans are based on the Project Management Plan, this Plan and the Contract. A plan may relate to other plans | ||
| h | All
documentation is based on this Plan and other related plans, documents
and reports |
||
|
Consideration
should be given to add a column to Tables 1, 2, and 3 to show
documentation dependences, e.g., Documentation A depends on
Documentation B (e.g., Implementation Plan depends on the Installation
and Training Plans). Another
consideration is documentation hierarchy, especially if documentation
has duplication of information, delineate which documentation has
precedence if one or more of the documentation has erroneous information
due to project evaluation, i.e., to minimize updating. |
|||
| 1. | A plan describes the “what, when and how” a task/activity will be performed | ||
| 2. | A
document contains information
on a
particular subject. |
||
| 3. | A report or record provides the status or history of the subject topic | ||