Practice: Documentation and Training
This practice describes how to prepare documentation for a product release and how that documentation might be used to prepare and deliver training to end users and support personnel.
Purpose

The purpose of this practice is to harden the product before a release by documenting key aspects for use by multiple audiences and by providing training to end users who will take delivery of the product when it is released.

Main Description

In almost every case, a product under development needs some amount of documentation for use by those who use its features and those who are responsible for keeping the system functioning and available. Because neither of these areas are strengths of the software development community, two new roles have been introduced that take advantage of the experience and expertise of niche support staff often found in or around an IT organization.

By playing to the strengths and availability of Technical Writers, Course Developers, and Trainers, a Development Team does not need to worry about who will write the user documents and train end users - in this case, they can have the specialists accept those responsibilities. Also, working with these two specialists ultimately will improve the development team's ability to articulate details of the system that they are building and provide insight into subtle ways to better comment and document their code.

Virtually all applications that are developed will be used or supported by people. Very often, however, both the documentation and training aspects of systems implementation are overlooked or not given enough emphasis. Inattention to these areas can result in a product that does not achieve its full business value because the people who should benefit from the application are not fully informed or trained.

Although this practice is documented and adopted at the development team level, in some organizations it may be advantageous to consolidate and integrate all types of documentation and training materials at the program level and deliver one comprehensive package to stakeholders, end users, and IT operations support personnel for the entire release across the program.

How to read this practice

With this practice, basic guidance regarding how to develop documentation and training, and more importantly why, are provided here. The best way to read this practice is to become familiar with its overall structure, what is in it, and how it is organized.

There are two related parts to this practice: 1) Documentation, and 2) Training. The documentation activity normally feeds the training effort. There are three basic types of documentation, each of which is meant for a different audience, and each has its own purpose.

  • Product
  • User
  • Support

A combination of the Product Documentation and User Documentation, with User Stories and Nonfunctional Requirements, are used in the development of User Training.

Product Documentation, with the Architecture Notebook and any design artifacts, are used to create Support Documentation.

Start with the tasks for creating the different types of documentation. Then, review the work products that result from those tasks. Next, review the tasks of the training activity. Notice that there is only one task that produces two different types of training materials (end user and support materials), because the process is the same for both (unlike the process for developing the three types of documentation). There are two tasks for training delivery because the end user training often is formal in nature and support training usually is informal.

Relationships