![](media/image1.jpeg){width="3.3333333333333335in"
height="0.9888888888888889in"}

Table of Contents

[Introduction 3](#introduction)

[Purpose 3](#purpose)

[Audience 3](#audience)

[The Process - in a Nutshell 3](#the-process---in-a-nutshell)

[Preliminary Planning 4](#preliminary-planning)

[Develop a Documentation and Training Plan
4](#develop-a-documentation-and-training-plan)

[Project Registration 5](#project-registration)

[Request A Mentor 5](#request-a-mentor)

[Prepare Documentation and Training
6](#prepare-documentation-and-training)

[When your team is ready to start developing the documentation and
training materials, some of the following elements should be considered.
6](#when-your-team-is-ready-to-start-developing-the-documentation-and-training-materials-some-of-the-following-elements-should-be-considered.)

[Communication 6](#communication)

[Ready to write 6](#ready-to-write)

[Troubleshooting 8](#troubleshooting)

[Preliminary Reviews 8](#preliminary-reviews)

[Review (D&T Workspace) 8](#review-dt-workspace)

[References and Resources 9](#references-and-resources)

[References 9](#references)

[Summary of Links and Resources 9](#summary-of-links-and-resources)

[Appendix 1 Sample Documentation & Training Plan
11](#appendix-1-sample-documentation-training-plan)

[Appendix 2 Other Considerations for Developing a D&T Plan
13](#appendix-2-other-considerations-for-developing-a-dt-plan)

[Roles of authors and reviewers 13](#roles-of-authors-and-reviewers)

[Collaborative authoring 13](#collaborative-authoring)

[Reviews 13](#reviews)

[Timelines & Schedules 14](#timelines-schedules)

[Defining deliverables & audience 14](#defining-deliverables-audience)

[Strategy, Workflow and Toolsets (i.e. Templates):
15](#strategy-workflow-and-toolsets-i.e.-templates)

####  {#section .unnumbered}

## Introduction

+-------------+--------------------------------------------------------+
| ##          | The development of documentation and training          |
| ### Purpose | materials is one of the most effective methods to      |
|             | convey information about a software application to the |
|             | broader community and is a key factor to secure        |
|             | successful implementation, adoption and acceptance     |
|             | beyond the initial development environment.^1^         |
|             |                                                        |
|             | Development of quality documentation and training      |
|             | materials can be a time-consuming and arduous task.    |
|             | To assist with this, the Cancer Bioinformatics Grid    |
|             | (caBIG™) Documentation and Training Workspace (D&T WS) |
|             | has created and assembled a variety of resources       |
|             | including templates, mentoring, and reviews. These     |
|             | tools are intended to help project teams developing in |
|             | the caBIG™ environment produce documentation and       |
|             | training materials more efficiently and in a           |
|             | consistent caBIG™ compliant manner.                    |
|             |                                                        |
|             | This *Getting Started Guide* provides caBIG™ project   |
|             | teams guidance into the steps involved and resources   |
|             | available from the D&T WS as well as some best         |
|             | practices gleaned from previous caBIG™ projects. Much  |
|             | of the material covered here can also be found on the  |
|             | caBIG™ website, Training Portal link located at:       |
|             | <https://cabig.nci.nih.gov/training>.                  |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ###         | This primary audience for this guide are the caBIG™    |
| ## Audience | project teams (Developers/Adopters) and the workspace  |
|             | leads who are shepherding the Statement of Work (SOW)  |
|             | process.  It should be reviewed, ideally, at the time  |
|             | that an initial project SOW is being drafted and then  |
|             | referred to later on when D&T development begins.      |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| #           | The D&T Workspace has broadly defined 5 basic steps    |
| #### The Pr | for developing documentation and training materials.   |
| ocess - in  |                                                        |
| a Nutshell  | **1. Preliminary Planning** - develop a Documentation  |
|             | and Training (D&T) plan                                |
|             |                                                        |
|             | **2. Register project** - notify the D&T WS about the  |
|             | project and allow WS members to plan and schedule the  |
|             | review of the D&T submitted                            |
|             |                                                        |
|             | **3. Request a Mentor** - optional resource available  |
|             | from D&T WS for project teams (for assistance and      |
|             | guidance )                                             |
|             |                                                        |
|             | **4. Prepare D&T** - Draft and test material           |
|             | (including technical review) by the project team       |
|             |                                                        |
|             | **5. Review** - Submit documentation and training      |
|             | materials to D&T WS for editorial review               |
|             |                                                        |
|             | More detailed information on these steps can be found  |
|             | on the caBIG™ website in the D&T Registration,         |
|             | Mentoring and Review process review document at:       |
|             | <ht                                                    |
|             | tps://cabig.nci.nih.gov/training/caBIG_review_doc.pdf> |
+-------------+--------------------------------------------------------+

## 

## Preliminary Planning

+-------------+--------------------------------------------------------+
| ###         | At the time your team is drafting the initial          |
| ## Develop  | Statement of Work (SOW) your team should begin         |
| a Documenta | developing a documentation and training plan.          |
| tion and Tr | Ideally, project teams should identify a strategy,     |
| aining Plan | workflow and tool set^1^ for accomplishing this task.  |
|             | Doing this early on in the project planning phase      |
| ###         | ensures that adequate estimates for resources and time |
|   {#section | have been built-in to the overall development plan and |
| -2 .Style-H | responsibilities and tasks have been clearly           |
| eading-3-+} | delineated.                                            |
|             |                                                        |
|             | Admittedly, the scope, type and nature of required     |
|             | materials for documentation and training will vary     |
|             | with each project depending on the type of software,   |
|             | pre-existing material (if any) and your potential      |
|             | audience (users).                                      |
|             |                                                        |
|             | Below are some common elements that can be included    |
|             | (*adapted from Technical Publications Style Guide,     |
|             | Chapter 2*):^2^                                        |
|             |                                                        |
|             | -   List of known content/core functionalities to      |
|             |     include in D&T                                     |
|             |                                                        |
|             | -   Preliminary analysis of potential audience for D&T |
|             |     (perceived user base)                              |
|             |                                                        |
|             | -   Assessment of pre-existing materials (if any) to   |
|             |     reference or integrate into D&T                    |
|             |                                                        |
|             | -   List of materials that will be delivered (i.e.     |
|             |     Admin Guide, Users manual, ...)                    |
|             |                                                        |
|             | -   Names of writers who will author D&T materials     |
|             |                                                        |
|             | -   Names of reviewers (ideally, include both          |
|             |     technical and editorial)                           |
|             |                                                        |
|             | -   List of known risks that may affect the delivery   |
|             |     of the documentation or training                   |
|             |                                                        |
|             | -   Schedule of deadlines for documentation & training |
|             |     delivery (based on release dates & code freeze for |
|             |     application development)                           |
|             |                                                        |
|             | A D&T Plan need not be a long, detailed document.  It  |
|             | can be incorporated into the broader project plan or   |
|             | kept distinct.  An example is provided in Appendix 1.  |
|             | *It should be noted that this is just an example and   |
|             | should not be considered a template.*  Each project    |
|             | will have its unique requirements that need to be      |
|             | taken into account.                                    |
|             |                                                        |
|             | More detailed considerations for developing a D&T Plan |
|             | can be found in Appendix 2.                            |
+-------------+--------------------------------------------------------+

## Project Registration

Once you\'ve drafted your D&T plan, it is time to register your
project.  This is a fairly quick step.  Simply fill out the Project
Registration Form from the caBIG™ Training Portal and email NCICB at
address listed on form. 

**Registration Form:**
<https://cabig.nci.nih.gov/training/App1RegistrationForm.doc>

This notifies the National Cancer Institute Center for Bioinformatics
(NCICB) as well as the D&T Workspace that a new project has started and
allows workspace members to plan and schedule for the review.

## 

## Request A Mentor

This can be done simultaneously with project registration.   Simply fill
out the Mentor Request Form from the caBIG™ website Training Portal and
email to NCICB at the address listed on the form.  This is an optional
service provided by the D&T WS.

**Mentor Request Form:**
<https://cabig.nci.nih.gov/training/App3MentorRequest.doc>

This notifies the NCICB as well as the D&T Workspace that your project
team would like the assistance of a mentor and allows the D&T workspace
to review and assign an appropriate person.  The assigned mentor will
then contact the project manager to develop a mentoring plan.

+-------------+--------------------------------------------------------+
| **NOTE:**   | Mentors can be a tremendous resource for project teams |
|             | and if you request one you should take advantage of    |
| #####       | them. Consult with them early and often, i.e. have     |
|             | them review your Documentation and Training Plan or    |
| ![](me      | review writing samples.  Ask questions and continually |
| dia/image2. | check in with them, especially if your plans change.   |
| wmf){width= | They are your liaison with the D&T WS as well as a     |
| "0.55347222 | guide and sounding board.                              |
| 22222223in" |                                                        |
| height="    | Using them is recommended for project teams that are   |
| 0.519444444 | developing their first caBIG™ application or seasoned  |
| 4444445in"} | caBIG™ developers who plan to undergo a significantly  |
|             | different methodology or technique for their D&T.      |
| #####       |                                                        |
+-------------+--------------------------------------------------------+

## 

## Prepare Documentation and Training

#### When your team is ready to start developing the documentation and training materials, some of the following elements should be considered. 

+-------------+--------------------------------------------------------+
| ##### Co    | The project manager or primary D&T editor should       |
| mmunication | establish and maintain open dialogs between writers,   |
|             | developers, QA and subject matter experts throughout   |
|             | the D&T development process.^1^  Check-in with the     |
|             | contributing authors and reviewers to assess progress  |
|             | and adjust timelines as needed.  Provide updates to    |
|             | all contributing team members so roles,                |
|             | responsibilities and expectations are clear.           |
|             |                                                        |
|             | Similarly, it is important to also communicate with    |
|             | the D&T workspace, either through your mentor, email,  |
|             | or direct participation in the workspace. Share        |
|             | details about the tool, use-case and end-user audience |
|             | as well as any changes in the project deliverables or  |
|             | timeline. This will help avoid any misunderstanding    |
|             | about deliverables when it comes time for the D&T WS   |
|             | to review your material.                               |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ##### Rea   | You\'ve figured out which templates to use, reviewed   |
| dy to write | examples and now you are ready to begin writing.  At   |
|             | this point, there are a few more things you may want   |
|             | to do first.                                           |
|             |                                                        |
|             | 1\. Look at the *Reviewers Checklist* on the caBIG™    |
|             | Training webpage, under Review (there is one for       |
|             | Documentation and one for Training).                   |
|             |                                                        |
|             | **Reviewers Guidelines:**                              |
|             | <https://cabig.nci.nih.gov/training/evaluation.html>   |
|             |                                                        |
|             | Print out and have handy as you begin writing.  This   |
|             | reveals what the D&T WS reviewers will be looking for  |
|             | in your materials.  Incorporating these into your      |
|             | writing at the start should result in a quicker review |
|             | with a minimum of surprises.                           |
|             |                                                        |
|             | 2\. Review and use the conventions suggested by the    |
|             | Technical Publications Style Guide at:                 |
|             |                                                        |
|             | **Style Guide**                                        |
|             | [https://cabig.nc                                      |
|             | i.nih.gov/training/Technical_Style_Guide.pdf](https:// |
|             | cabig.nci.nih.gov/training/Technical_Style_Guide.pdf ) |
|             |                                                        |
|             |                                                        |
|             | For the caBIG™ Templates, focus on Chapters 3, 4  and  |
|             | 7.  Keep in mind that several of the format and style  |
|             | elements mentioned in this guide are already pre-built |
|             | into these templates.                                  |
|             |                                                        |
|             | 3\. In addition to the elements described in #1 & 2    |
|             | above, below are a few more best practices to keep in  |
|             | mind as you write.                                     |
|             |                                                        |
|             | -   Be sure to check and make sure you are working off |
|             |     the most recent version template(s).  The caBIG™   |
|             |     website (Training Portal) is the best place to     |
|             |     check but if in doubt, contact the D&T workspace   |
|             |     or your D&T mentor.                                |
|             |                                                        |
|             | -   If you have questions or want to deviate           |
|             |     significantly from the templates, consult with     |
|             |     your mentor or the D&T workspace first.            |
|             |                                                        |
|             | -   Make sure to note the version and name of the      |
|             |     software that you are developing documentation and |
|             |     training for.                                      |
|             |                                                        |
|             | -   Ensure manual is titled appropriately and stay on  |
|             |     topic (i.e. don\'t title it a Programmers Guide    |
|             |     when it\'s actually an Administration              |
|             |     Manual).  Consult with your mentor or D&T          |
|             |     workspace if you are unsure.                       |
|             |                                                        |
|             | -   Initially, try to avoid getting too bogged down    |
|             |     with formatting. It may be better to defer         |
|             |     formatting until after primary content is          |
|             |     completed.^1^                                      |
|             |                                                        |
|             | -   Repeating document components (i.e. task           |
|             |     descriptions) should be prototyped early with      |
|             |     users to test organization and style before they   |
|             |     are used throughout the documents^1^ (adopters can |
|             |     do this).                                          |
|             |                                                        |
|             | -   Early on, have a short writing segment reviewed by |
|             |     your mentor, external reviewer or naïve adopter    |
|             |     for clarity and usability.  Authors should strive  |
|             |     for conciseness and clarity of expression.  Once   |
|             |     approved, share the sample with contributing       |
|             |     authors.                                           |
|             |                                                        |
|             | -   When writing step-by-step instructions (especially |
|             |     useful for installation instructions), make sure   |
|             |     they are clear, numbered, concise and distinct     |
|             |     from preceding and following text.                 |
|             |                                                        |
|             | -   When writing installation instructions, be sure to |
|             |     include instructions for uninstalling as well as   |
|             |     validation to ensure that the install was          |
|             |     successful.                                        |
|             |                                                        |
|             | -   When using caBIG™ templates, be sure to delete     |
|             |     explanatory or instructional (blue and red) text   |
|             |     from templates before submitting for review.       |
|             |                                                        |
|             | -   With documentation, it is recommended that         |
|             |     chapters start on odd pages, especially if primary |
|             |     distribution will be printed and bound.            |
|             |                                                        |
|             | -   Use of a screen-capture tool such as \"SnagIt\"    |
|             |     can help with creation of figures (i.e. screen     |
|             |     shots).  Saving the figures to PNG format works    |
|             |     well.                                              |
|             |                                                        |
|             | -   Make sure references caBIG have the following      |
|             |     trademark symbol, \" caBIG™ \"                     |
|             |                                                        |
|             | -   Acronyms should be spelled out the first time they |
|             |     are used.                                          |
+-------------+--------------------------------------------------------+

+--------------+-------------------------------------------------------+
| ##### Tro    | MS Word driving you crazy?  Common problems and       |
| ubleshooting | resources.                                            |
|              |                                                       |
|              | -   How to add a captions & configure numbering to    |
|              |     figures, tables, etc.                             |
|              |     <http://support.microsoft.com/kb/313017/en-us>    |
|              |                                                       |
|              | -   How to create a table of contents by marking text |
|              |     in Word:                                          |
|              |     <http://support.microsoft.com/kb/285059/en-us>    |
+--------------+-------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ###         | Consider conducting both technical and editorial       |
| ## Prelimin | reviews.  Although they can be conducted               |
| ary Reviews | simultaneously - it is preferable that the technical   |
|             | occur first.  Remember, the review conducted by D&T WS |
|             | is an editorial review only.                           |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| **NOTE:**   | Before submitting to D&T WS for review, it is          |
|             | recommended that someone else, skilled in written      |
| #####       | English and not intimately involved in the initial     |
|             | writing or software development,  proofread the        |
| ![](me      | material first.  For example, have a naïve user        |
| dia/image2. | work-through through a draft of your User\'s Manual.   |
| wmf){width= |                                                        |
| "0.55347222 |                                                        |
| 22222223in" |                                                        |
| height="    |                                                        |
| 0.519444444 |                                                        |
| 4444445in"} |                                                        |
|             |                                                        |
| #####       |                                                        |
+-------------+--------------------------------------------------------+

## Review (D&T Workspace)

When you\'ve finished your draft and conducted preliminary reviews, it
is then time to submit to the D&T Workspace for review.  To do so,
complete this brief form and submit it to NCICB at the the e-mail listed
on the form.  This will indicated to the D&T WS reviewers what is being
submitted and where to find it. Separate forms can be submitted for each
module as they are ready. 

**Documentation and Training Module Submission Form:**
[https://cabig.nci.nih.gov/training/App6DTSubmittal.doc](../ https://cabig.nci.nih.gov/training/App6DTSubmittal.doc)

Typically, the D&T WS reviews are conducted in two parts, a draft review
and a final follow up review. If initial draft reviews are in near final
form with minimal changes needed, then one review may be all that\'s
needed.

+-------------+--------------------------------------------------------+
| **NOTE:**   | It is recommended that manuals/modules be submitted to |
|             | the D&T WS as soon as they are ready (i.e. one at a    |
| #####       | time) rather than waiting to submit them altogether in |
|             | a batch.  This is easier on the reviewers\' time and   |
| ![](me      | also allows the benefit of perpetuating some of the    |
| dia/image2. | reviewers\' feedback into the other, yet unfinished    |
| wmf){width= | drafts.                                                |
| "0.55347222 |                                                        |
| 22222223in" |                                                        |
| height="    |                                                        |
| 0.519444444 |                                                        |
| 4444445in"} |                                                        |
|             |                                                        |
| #####       |                                                        |
+-------------+--------------------------------------------------------+

## References and Resources

Most of the links and documents mentioned below can be found on the
caBIG™ Training Portal website:
[https://cabig.nci.nih.gov/training](../%20https://cabig.nci.nih.gov/training)

+-------------+--------------------------------------------------------+
| #####       | 1.  User Documentation White Paper:                    |
|  References |     <http:                                             |
|             | //jhh.opi.upmc.edu/main/cabig/DocumentationWhitePaper> |
|             |                                                        |
|             | 2.  Technical Publications Style Guide (Ch1&2):        |
|             |     <https://                                          |
|             | cabig.nci.nih.gov/training/Technical_Style_Guide.pdf>  |
+-------------+--------------------------------------------------------+

##### Summary of Links and Resources

+-------------+--------------------------------------------------------+
| **          | -   Technical Publications Style Guide (Ch1&2):        |
| Preliminary |     <https://                                          |
| Planning**  | cabig.nci.nih.gov/training/Technical_Style_Guide.pdf>  |
|             |                                                        |
|             | -   User Documentation White Paper:                    |
|             |     <http:                                             |
|             | //jhh.opi.upmc.edu/main/cabig/DocumentationWhitePaper> |
|             |                                                        |
|             | -   Developing caBIG Training Modueles - A how to      |
|             |     guide:                                             |
|             |     <https:/                                           |
|             | /cabig.nci.nih.gov/training/GuidetoTraining-FINAL.pdf> |
|             |                                                        |
|             | -   Developing caBIG™ Training: Training Approaches &  |
|             |     Testing:                                           |
|             |     <http                                              |
|             | s://cabig.nci.nih.gov/training/TrainingAlts-FINAL.pdf> |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| **Project   | -   Project Registration Form:                         |
| I           |     <https:                                            |
| nitiation** | //cabig.nci.nih.gov/training/App1RegistrationForm.doc> |
|             |                                                        |
|             | -   Mentor Request Form:                               |
|             |     <htt                                               |
|             | ps://cabig.nci.nih.gov/training/App3MentorRequest.doc> |
|             |                                                        |
|             | -   D&T Registration, Mentoring and Review process     |
|             |     review document:                                   |
|             |     [https:                                            |
|             | //cabig.nci.nih.gov/training/caBIG_review_doc.pdf](htt |
|             | ps://cabig.nci.nih.gov/training/caBIG_review_doc.pdf ) |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| **Docu      | -   Technical Style Guide:                             |
| mentation** |     <https://                                          |
|             | cabig.nci.nih.gov/training/Technical_Style_Guide.pdf>  |
|             |                                                        |
|             | -   Reviewers Guidelines:                              |
|             |                                                        |
|             |   <https://cabig.nci.nih.gov/training/evaluation.html> |
|             |                                                        |
|             | -   caBIG™ MS Word Templates:                          |
|             |     <https://cabig.nci.nih.                            |
|             | gov/working_groups/Training_SLWG/Documents/index_html> |
|             |                                                        |
|             | -   User Documentation White Paper (Harrison):         |
|             |     <http:                                             |
|             | //jhh.opi.upmc.edu/main/cabig/DocumentationWhitePaper> |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| *           | -   Audience Analysis template:                        |
| *Training** |     <https://cabi                                      |
|             | g.nci.nih.gov/training/Audience_Analysis-Template.doc> |
|             |                                                        |
|             | -   Reviewers Guidelines:                              |
|             |                                                        |
|             |   <https://cabig.nci.nih.gov/training/evaluation.html> |
|             |                                                        |
|             | -   caBIG™ MS PowerPoint Templates:                    |
|             |     [https://cabig.nci.nih.gov/working_groups/Train    |
|             | ing_SLWG/Documents/index_html](https://cabig.nci.nih.g |
|             | ov/working_groups/Training_SLWG/Documents/index_html ) |
|             |                                                        |
|             | -   Developing caBIG™ Training Modueles - A how to     |
|             |     guide:                                             |
|             |     [https://cabig.nc                                  |
|             | i.nih.gov/training/GuidetoTraining-FINAL.pdf](https:// |
|             | cabig.nci.nih.gov/training/GuidetoTraining-FINAL.pdf ) |
|             |                                                        |
|             | -   Developing caBIG™ Training: Training Approaches &  |
|             |     Testing:                                           |
|             |     <http                                              |
|             | s://cabig.nci.nih.gov/training/TrainingAlts-FINAL.pdf> |
|             |                                                        |
|             | -   Testing Strategies: To Test or Not to Test?        |
|             |     Criteria for Including Testing with caBIG™         |
|             |     Training:                                          |
|             |     <h                                                 |
|             | ttps://cabig.nci.nih.gov/training/TestingCriteria.ppt> |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| **Review**  | -   Documentation and Training Module Submission Form: |
|             |     [ https:/                                          |
|             | /cabig.nci.nih.gov/training/App6DTSubmittal.doc](../ h |
|             | ttps://cabig.nci.nih.gov/training/App6DTSubmittal.doc) |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| **General** | -   D&T WS Questions and Answers listerv               |
|             |     (CABIG_BC_TRAIN-L):                                |
|             |     [https://list.nih.gov](https://list.nih.gov/)/     |
|             |                                                        |
|             | -   D&T WS Lead:  Jennifer Tucker                      |
|             |     (<jtucker@typetalk.com> )                          |
+-------------+--------------------------------------------------------+

## Appendix 1 Sample Documentation & Training Plan

> **Project:  \"caTool\"**

  ------------------------------ ------------------------- ---------------
  **Deliverables**               **Writers/Authors**       **Reviewers**

  **Administration Guide**       Joe S\*, Jane D           Mark B \--\>
  (include architectural                                   tech\
  description, install                                     Mary D \--\>
  instructions, and release                                edit
  notes)                                                   

  **User Manual**                Lisa S\*,  Mac J & Jenny  Mary D \--\>
                                 O, Joe S, & Jane D        tech\
                                                           Josh A \--\>
                                                           edit

  **Hands On Training via CBT**  Jenny O\*, Mark D.        Jim E \--\>
                                                           both

  **Follow up  - updates and     Joe S\*                   
  errata**                                                 
  ------------------------------ ------------------------- ---------------

 \* Primary editor  

  ---------------------------------------------- ------------------------
  **Key Project Milestones **                    **Date**

  SOW submittal                                  Oct 30th, 2006

  Finish requirements gathering                  Dec 31st, 2006

  Finish Phase 1, 2 & 3 of development           April 14, 2007 

  Estimated Code and UI Freeze for caTool        April 15, 2007

  Prepare and Finish D&T                         July 31st, 2007

  Submit Lessons Learned                         Aug 15th 2007
  ---------------------------------------------- ------------------------

+----------------------------+-----------------------------+-----------+
| **D&T Tasks**              | **Sub-tasks**               | **D       |
|                            |                             | uration** |
+----------------------------+-----------------------------+-----------+
| **Draft and Submit D&T     | -   Assessment of already   | 2 weeks   |
| Plan**                     |     existing materials      |           |
|                            |     relating to caTool      |           |
|                            |                             |           |
|                            | -   Audience Analysis       |           |
|                            |                             |           |
|                            | -   Select methods, tools   |           |
|                            |     (i.e. templates) and    |           |
|                            |     key deliverables for    |           |
|                            |     D&T                     |           |
|                            |                             |           |
|                            | -   Assemble D&T team       |           |
|                            |     (writers & reviewers    |           |
+----------------------------+-----------------------------+-----------+
| **Register Project and     |                             | 1 day     |
| request Mentor with D&T    |                             |           |
| WS**                       |                             |           |
+----------------------------+-----------------------------+-----------+
| **Review D&T Plan with D&T |                             | 1 week    |
| WS Mentor**                |                             |           |
+----------------------------+-----------------------------+-----------+
| **Assemble core            |                             | 1 week    |
| functionalities of         |                             |           |
| caTool**                   |                             |           |
+----------------------------+-----------------------------+-----------+
| **Review D&T Style Guide & |                             | 1 week    |
| other relevant materials** |                             |           |
+----------------------------+-----------------------------+-----------+
| **Prepare Documentation**  | -   Draft core content      | 5 weeks   |
| (same steps apply for each |     outline(s)              |           |
| manual)                    |                             |           |
|                            | -   Discuss outline,        |           |
|                            |     template selection with |           |
|                            |     D&T mentor & project    |           |
|                            |     team                    |           |
|                            |                             |           |
|                            | -   Review small writing    |           |
|                            |     sample for clarity,     |           |
|                            |     style and format w/D&T  |           |
|                            |     mentor & reviewers.     |           |
|                            |     Submit to all authors   |           |
|                            |     when Ok\'d.             |           |
|                            |                             |           |
|                            | -   Contributing authors    |           |
|                            |     draft assigned chapters |           |
|                            |                             |           |
|                            | -   Finish Draft  (collate  |           |
|                            |     all chapters)           |           |
+----------------------------+-----------------------------+-----------+
| **Prepare Training**       | -   Draft core content      | 4 weeks   |
|                            |     outline(s)              |           |
|                            |                             |           |
|                            | -   Discuss outline,        |           |
|                            |     template selection &    |           |
|                            |     with D&T mentor &       |           |
|                            |     project team            |           |
|                            |                             |           |
|                            | -   Review small sample     |           |
|                            |     presentation for        |           |
|                            |     clarity, style and      |           |
|                            |     format w/D&T mentor &   |           |
|                            |     reviewers               |           |
+----------------------------+-----------------------------+-----------+
| **Review & Test Training & |                             | 2 weeks   |
| Revise**                   |                             |           |
+----------------------------+-----------------------------+-----------+
| **Submit to D&T WS for     |                             | 2 weeks   |
| Review & Revise**          |                             |           |
+----------------------------+-----------------------------+-----------+
| **Continual Updates and    |                             | Ongoing   |
| Errata**                   |                             |           |
+----------------------------+-----------------------------+-----------+

**Dependencies**

-   Documentation depends on finishing application development and code
    freeze

-   Completion of Training depends on completion of Documentation

-   Review and submittal of final deliverables depends of finishing
    drafts D&T

**Risks**

-   Completion of development could be delayed due to holidays

-   Risk that segments may not be submitted on time by some authors -
    review timelines and expectations w/ authors (get
    confirmation/commitment)

-   Mary D has jury duty in July (affects reviews) -- Shelly A. will
    backup as needed.

## 

## Appendix 2 Other Considerations for Developing a D&T Plan

+-------------+--------------------------------------------------------+
| ###         | Every project will have its own unique considerations, |
| ## Roles of | resources and constraints which will affect how        |
|  authors an | project teams determine roles & responsibilities.  As  |
| d reviewers | a team considers who will be authors and reviewers,    |
|             | the following things should be considered.  Typically, |
|             | developers and technically-knowledgeable domain        |
|             | experts create the detailed content with project       |
|             | managers and technical writers developing introductory |
|             | materials, acronym lists, indexes and performing       |
|             | editing.^1^   With caBIG™ projects, the technical      |
|             | manuals (Admin, Installation, Release Notes) are       |
|             | typically written by the developers, while end user    |
|             | manuals are written by advanced users at the adopters  |
|             | sites.  Adopter sites can also play key roles in       |
|             | performing technical and/or first pass editorial       |
|             | reviews.  Segments can be divided (i.e. by Chapter)    |
|             | and assigned to different authors.                     |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ##### C     | If documentation or training is to be developed        |
| ollaborativ | collaboratively with multiple contributing authors, it |
| e authoring | is advisable to designate one or two primary editors   |
|             | who will be responsible for collating and pulling      |
|             | together material from contributing authors.  These    |
|             | individuals should have a skills in written English    |
|             | and, if using the caBIG™ D&T templates, be familiar    |
|             | with Microsoft Word or PowerPoint advanced formatting  |
|             | features.  Depending on how roles are defined within   |
|             | the project, it can often be the case that these       |
|             | primary editors are contributing significantly more    |
|             | time and effort and this should be adequately          |
|             | reflected in resource utilization.                     |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ##          | Consider conducting both a technical and editorial     |
| ### Reviews | review.  Technical reviews focus on content and        |
|             | accuracy (i.e. installing of application, working      |
|             | through steps and detecting missing steps). Editorial  |
|             | reviews focus on readability, grammar, syntax, format  |
|             | and style.  Although they can be conducted             |
|             | simultaneously, it is preferable that the technical    |
|             | occur first.^2^  It\'s helpful to have a second pair   |
|             | of eyes, outside of the original authors, review the   |
|             | material.                                              |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| **NOTE:**   | The reviews mentioned above are distinct from the D&T  |
|             | WS review.  The review conducted by D&T WS is an       |
| #####       | editorial review only.  *Technical reviews and         |
|             | first-pass editorial reviews are the responsibility of |
| ![](me      | the Developer/Adopter project teams.*                  |
| dia/image2. |                                                        |
| wmf){width= |                                                        |
| "0.55347222 |                                                        |
| 22222223in" |                                                        |
| height="    |                                                        |
| 0.519444444 |                                                        |
| 4444445in"} |                                                        |
|             |                                                        |
| #####       |                                                        |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| #####       | Remember that developing documentation is an important |
|  Timelines  | activity that should not be short-changed.  Be sure to |
| & Schedules | allow adequate time for its development and review.    |
|             | Typically, D&T development begins in earnest at the    |
|             | time that software development for a particular        |
|             | version has ceased (code freeze).  However, assembling |
|             | core functionalities, template selection, and chapter  |
|             | outlines can worked on prior to this and is            |
|             | recommended.  Deadlines should allow for review of the |
|             | sections by the team and by external reviewers before  |
|             | the document is finalized and submitted for review to  |
|             | the D&T WS.  Be sure to leave enough lead time for the |
|             | D&T workspace to review as well (approximately 2       |
|             | weeks).  Typically they first review a draft and then  |
|             | a final version. \                                     |
|             | \                                                      |
|             | Training material should be prepared after             |
|             | documentation is written and has at least passed       |
|             | through technical review.  Additional time should be   |
|             | allotted if the project team determines that training  |
|             | will need to be accompanied with testing.              |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| #####       | The deliverables needed for the software application   |
|  Defining d | will be determined not only by the features of the     |
| eliverables | application itself but also by the intended audience   |
|  & audience | or end-user. The audience for your D&T should be       |
|             | identified and clearly defined early on.  This will    |
|             | factor into the decision regarding the type of         |
|             | deliverables and method of delivery your team chooses  |
|             | for D&T. With caBIG™ projects, keep in mind that the   |
|             | potential audience (user base) will likely extend      |
|             | beyond the initial adopters designated in the SOW.     |
|             | Consider the spectrum and likely background of your    |
|             | potential user base.                                   |
|             |                                                        |
|             | An audience analysis template for caBIG™ Training can  |
|             | be found at the following link within the caBIG™       |
|             | Training Portal:                                       |
|             |                                                        |
|             | **Audience Analysis:**                                 |
|             | <https://cabi                                          |
|             | g.nci.nih.gov/training/Audience_Analysis-Template.doc> |
+-------------+--------------------------------------------------------+

+-------------+--------------------------------------------------------+
| ##### Strat | The caBIG™ D&T WS has provided a variety of tools      |
| egy, Workfl | including Microsoft Word & PowerPoint templates,       |
| ow and Tool | samples, guides, and mentors to help project teams     |
| sets (i.e.  | develop their D&T.  Employing tools that               |
| Templates): | allow deployment in multiple formats (paper, web,      |
|             | local electronic help files) from a single text corpus |
|             | will provide the most advantage for long term          |
|             | maintenance and updates.  These can then be abstracted |
|             | into tutorials and other needed forms of training      |
|             | material.  Your team may also want to consider the use |
|             | of some sort of collaborative authoring tools (e.g. a  |
|             | Wiki) to develop your documentation. ^1^               |
|             |                                                        |
|             | The caBIG™ MS Word and PowerPoint templates can be     |
|             | found on the caBIG™ Training Portal at:                |
|             |                                                        |
|             | **Templates:**\                                        |
|             | <https://cabig.nci.nih.                                |
|             | gov/working_groups/Training_SLWG/Documents/index_html> |
+-------------+--------------------------------------------------------+

####