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.
Relationships
Content References | How to Adopt the Documentation and Training Practice Work Products Product Documentation Support Documentation Training Materials User Documentation Tasks Develop Product Documentation Develop User Documentation Develop Support Documentation Develop Training Materials Deliver End User Training Deliver Support Training Roles Course Developer Product Owner Technical Writer Trainer
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. Support 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.
This program and the accompanying materials are made available under the Eclipse Public License V1.0, which accompanies this distribution. EPF Copyright.