Managing document templates

The CollabNet Baseline Project provides document templates that project team members can use to do work that is relevant to particular project stages. The templates allow project owners to enforce standard methods of working across projects and across project members. For example, when creating a new use case, a project participant can open a copy of the use case template, save it to a new file, and use this as the basis for entering a new use case.

You may want to modify these templates to bring the styles in line with the standards for your organization or to modify the content.

The following table describes the templates that are provided with the CollabNet Baseline Project.

This page. . . Is associated with these templates. . .
Definition
  • Functional overview - This template gives guidance on how a requirement maps to a feature. Typically one specification is written per feature.
  • Functional specification - This template describes features in terms of the product's behavior as seen by a user. It defines the functionality, but it does not describe implementation strategy or details. It does provide technical information needed for design. Typically one specification is written per feature.
  • Marketing Requirements Document (MRD) - Typically, only one MRD is used per project.
  • Product Requirements Document (PRD) - Typically, only one PRD is used per project.
  • Requirements spreadsheet - Typically, only one spreadsheet is used per project.
  • Use case template description - This template gives guidance on how to use the use case template.
  • Use case template - This template gives guidance on creating a use case, including author, date, use case flows, preconditions, postconditions, and so on. Typically one use case is written per feature.
Design
  • Configuration Management Plan - This template covers all of the IEEE standard aspects of configuration management, including work product identification, naming, baseline creation, labels, branching, merging, and so on. Typically, one plan is written per release.
  • Design plan - This template's purpose is to capture important aspects of the new or updated design of the system. It provides sections intended to identify how the system is to be changed. Typically one specification is written per feature.
  • Software architecture document - This template provides guidance on the most critical decisions about software design, including components to be designed and relationships among them. Typically, one software architecture document is written per release.
  • Systems architecture document - This template provides guidance on the most critical decisions about the system-level elements and relationships between system-level elements. Typically, one systems architecture document is written per release.
Code & Build
  • Code review - This template explains how to document code review expectations and approach. It also provides questions to ask during a review.
  • Development guidelines - This template provides guidelines for developers.
Testing
  • Test case - This template that explains how to document an individual testing sequence. Typically, one test case is written per requirement.
  • Test plan - This template that explains how to document the scope of testing, items to be tested, testing approach, and so on. Typically, one test plan is written per release.
Deployment
  • Deployment checklist - This template gives guidance on documenting activities that lead to successful release of the software to customers.
  • Release management plan - This template that gives guidance on documenting release objectives, installation requirements, the pre-rollout meeting, post-implementation testing, and so on.
  • Release notes - This template gives guidance on documenting release highlights and customer-facing defects resolved in the release.
  • Software installation guide - This template gives guidance on documenting software installation, initial configuration, and start-up.
Support
  • Support plan - This template that gives guidance on documenting the support mission, support success criteria, support roles and responsibilities, and an area to capture a strategy for the ITIL-based support process areas. Typically, one support plan is written per release.
Project Management
  • Business case - This template provides sections for the business problem, proposal for a project that would solve the problem, and the project value proposition.
  • Project completion review - This template captures the lessons learned from a completed project based on using a strengths, weaknesses, opportunities, and threats (SWOT) method.
  • Project plan - This template provides sections for a project summary, scope, success criteria, lifecycle approach, assumptions, constraints, risk management plan, human resources plan, a work breakdown structure, an outside supplier plan, and so on.
  • Project schedules (Waterfall, Iterative, and Agile) - These are separate template files for each type of process.
Cruise Control
  • Code review - This template explains how to document code review expectations and approach. It also provides questions to ask during a review.
  • Development guidelines - This template provides guidelines for developers.
Test Director
  • Test case - This template that explains how to document an individual testing sequence. Typically, one test case is written per requirement.
  • Test plan - This template that explains how to document the scope of testing, items to be tested, testing approach, and so on. Typically, one test plan is written per release.

Customizing the document templates

When users view the landing page for a Stages subpage, or the Communications or Project Management page, they may see a table that contains project documentation. If the table is present, it means that a directory named "documents" has been created for that subpage or page. In addition, the users may see a link to a document templates page. This page contains sample documents upon which users can base their own project documentation. If a link to the document templates page is present, it means that a directory named "templates" has been created for that subpage or page.

You can add, modify, and remove the templates in the templates directory. When you check in your changes using your version control tool, the corresponding section of the Documentation Templates web page is updated. For example, if you modify a document template in the 1-Definition/templates directory, the "Definition" section of the Documentation Templates web page is updated.

Note: If a templates directory exists but a documents directory is missing, the Documents section of the page shows only the link to the templates. If a documents directory is present, only the list of documents is shown. And if neither the documents or templates directories are present, the entire Process Documents section is not shown.

To add or modify a process document template:

  1. Navigate to the template directory for a particular subpage or page.
    For example, you may go to project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Definition/templates
    Where My-Process is the name of the template directory.
  2. Copy an existing process document template and save it as a new file.
    For example, you could edit cn-project-pages/Stages/Definition/templates/Use-Case-template.doc
  3. Save the file locally, giving it a new name if you plan to create a new template based on an existing one.
  4. Edit the template file, or create a new template using this file as the basis.
  5. Using Subversion, replace the existing template or add the new process document template to the templates directory of the appropriate Stages subpage or for the Communications or Project Management pages.
    For example, you could add the document cn-project-pages/Stages/Definition/templates/My-New-template.doc.
  6. Using your version control tool, commit your changes.
    If you are adding a new process document template, it is automatically displayed in the templates page, in the appropriate section of that page.