You are here: TWiki > Documentation Web>DocHowTo (15 Feb 2012, KyleGross)

How To Manage, Write, Review, and Test OSG Documentation

Documentation
DocHowTo
Review Passed
by TedHesselroth
Released
by JamesWeichel

About This Document

hand This document is an overall reference for people playing any role in OSG official documentation; and, as such, contains or references all information about producing documentation in OSG. Shorter, more focused documents are available for people filling the three major roles in documentation:

The Documentation Process

The overall documentation process is described in this section. This includes information on how Owners, Reviewers, and Testers control the creation, review, and update of documents.

Process Introduction

There are three interrelated processes that involve documentation:
  1. Ownership/Review Process
  2. Testing/New Release Process
  3. Ongoing Evaluation/Improvement Process

Each of these are straightforward and take into account the low resource, collaborative environment of OSG. The first and third of these processes are owned by the Content Management Area Coordinator who is responsible for maintaining the process descriptions, changing the processes as needed, and managing the execution of the processes with the help of the Documentation Architect. The second process is owned and managed by the OSG Integration & Sites Coordinator.

Ownership/Review Process

Documents are separated into a set of areas, each with an owner that has overall responsibility for that area. The area owner manages the structure of the area's documentation and ensures the documents have the following roles assigned. Each document in the official OSG Documentation TWiki must have an Owner who is responsible for creation and/or maintenance/update of that document. Most documents will also have a Reviewer who is responsible for reviewing the document for content, accuracy, usability, and format. Documents that include procedures to be followed by the readers should also have a Tester who is responsible for testing the procedure to verify that it produces the expected results.

The steps in the Ownership/Review Process apply to all documents in the official OSG Documentation TWiki (currently WebHome and ReleaseDocumentation). The process is managed using TWiki variables that are set using an HTML comment in the documents. The names of the Owner, Reviewer, and Tester are also specified using variables (OWNER, REVIEWER, TESTER) in each document. The process steps are:

  1. For any new or existing document (that is not being depreciated), an Owner, Reviewer, and (optionally) a Tester are identified. These assignments can be proposed by the Area Owner, made by a person volunteering to take the role (preferred), by local management selection, or by the Area Owner and/or the Content Management Area Coordinator or Documentation Architect working in conjunction with the person and the person's local management.
  2. The Owner produces or makes the existing document conform to the standards/template (see Document Types and Templates) and marks the REVIEW_READY variable to %YES%. (The REVIEW_PASSED variable should be %IN_PROGRESS%.)
  3. The Reviewer reviews the document and marks the variable REVIEW_PASSED either %YES% or %NO%. If NO, then the Reviewer works in collaboration with the Owner to resolve issues with the document until the Reviewer is ready to mark the REVIEW_PASSED variable %YES%.
    1. If the document is a procedure or installation document, the Reviewer will mark the TEST_READY variable %YES%. (The TEST_PASSED variable should be %IN_PROGRESS%.) Note that the testing may be done in parallel with the review.
    2. The Tester will perform the test, document any problems, and mark the variable TEST_PASSED to %YES% (or %NO%).
    3. If the test failed, the Tester will collaborate with the Owner to resolve any issues discovered by the testing. When resolved the Tester will mark the variable TEST_PASSED to %YES%.
  4. When the Review and Owner are satisfied with the document and testing (if applicable) has succeeded, the Reviewer or Owner marks the RELEASE_READY variable to %YES%.

Or pictorially:
ProcessDiagram.png

Testing/New Release Process

This process applies to all documents in the ReleaseDocumentation Web. When a new release of the OSG software is being integrated, documented, and tested, the Integration & Sites Coordinator manages the process. That process uses the Owner, Reviewer, and Tester consistent with the Ownership/Review process above. The management of documents for major and minor releases is detailed in DocReleaseProcess.

Ongoing Evaluation/Improvement Process

This process covers the ongoing evaluation and improvement of OSG documentation. It makes use of user feedback in the form of comments and a document rating mechanism to identify documents or document areas in need of improvement. In addition the Document Architect and Content Management Area Coordinator may review messages in mailing lists and other information to identify areas needing improvement.

On a quarterly basis, a set of documents will be identified for improvement. The Owner and Reviewer for each of these will be asked to make improvements that will be tracked by the Document Architect. At the same time particularly well rated documents will be identified to use as examples of high-quality documents. Once a year, the best of our documents will be identified and their Owners and Reviewers will be recognized.

HELP NOTE
The user rating of documents is not yet implemented, so the parts of this section that require those ratings are not currently being done.

Use of _draft documents

Sometime as part of the Testing/New Release process or as part of the Ongoing Evaluation/Improvement process there is the necessity to make changes to a document and make these changes available to a selected number of people, e.g. testers and reviewers, without disrupting regular users, specially if the documentation changes refer to a new version of the OSG software that is not yet available in production.

The procedure in this cases is to:

  1. Create a copy of the existing document and add _draft to the original name (e.g. DocName becomes DocName_draft)
  2. On top of the document mark copy that it is a document and mention the version of the original document it was copied from. This should be done using the warning message: on top of the document define a variable DOC_BANNERMESSAGE, e.g.:
     DOC_BANNERMESSAGE = This document is a draft of !DocName, from version 15
  3. When the document is ready to be merged, the owner should merge changes that may have been committed to the original document in the mean time, copy and paste the document on top of the original one, double check that all the links work correctly

Document Classification and Organization

Documents in OSG are classified by Type and Role and are organized into document Areas.

Document Types and Templates

Documents can be of several different types. Types are defined in the following table and are specified in a document using the Content Management variable DOC_TYPE. The Templates are recommended formatting and sections to be included in the associated document type.
Document Type Definition Template
HowTo Documents telling how to do something. Other document types exist for specific procedures. (For example, see Installation and Troubleshooting.) DocHowToTemplate
Installation Documents describing the procedure for installation of software DocInstallTemplate
Knowledge Documents of a general nature and not of another type. (For example, general information, explanations, descriptions, and theoretical aspects of grid computing.) DocBasicTemplate
Navigation Documents supporting a person in navigating to other documents or the TWiki itself. DocBasicTemplate
Planning Documents supporting the planning of grid computing. (For example, Planning an OSG site.) DocBasicTemplate
Team Documents or webs for use by Teams. DocBasicTemplate
Training Documents designed for training or used organize or manage a training event. DocBasicTemplate
Troubleshooting Documents that support the resolution of typical problems that can to occur. DocTroubleshootingTemplate

Document User Roles

Each document is written for a person in a certain role (called primary role). It may also be used by people in another role (called the secondary role). Since few documents cover multiple roles, we do not specify a secondary role in a document. Roles are defined in the following table and are specified in a document using the Content Management variable DOC_ROLE.
Document Reader Role Definition
Any Used for general documents intended for any reader
Developer Software developers of grid applications
Documenter Any person working on documentation itself
Scientist A person submitting jobs to the Grid -- an "End User"
Student Any student, who is learning about any part of OSG. General training material might be for this role. Specific training written for another role would be classified as that role as primary.
SysAdmin A computer system administrator, managing a computing resource in OSG
VOManager A manager in a Virtual Organization as contrasted with one of the above roles

Document Areas

The documentation universe is segmented into a set of areas, each of which has an owner having overall responsibility for the documentation of that area. The Areas are defined in the following table and are specified in a document using the Content Management variable DOC_AREA.
Documentation Area Definition Area Owner
ComputeElement Documents describing the installation, operation or usage of a Compute Element AlainRoy
General General documents and documents about documentation itself AlainRoy
Integration Documents describing the integration and test of software into a package for the OSG. SuchandraThapa
Monitoring Documents describing resource Monitoring, Accounting, and Metrics TanyaLevshina
Operations Documents describing Operational procedures or related to GOC services ElizabethChism
Security Documents related to all aspects of Security of the Open Science Grid AnandPadmanabhan
SmallSite Documents supporting the installation and operation of Tier 3, Campus Grids, or other small sites in the OSG MarcoMambelli
Storage Documents describing the installation, operation or usage of a Storage Element DouglasStrain
User Documents for a Scientist or User of OSG resources GabrieleGarzoglio
VO Documents concerned with all aspects of a Virtual Organization. ChanderSehgal

Content Management Control Variables and Tracking

The OSG process of creation, update, review, and testing of documents is managed through the use of a set of Content Management Variables in an HTML block at the end of each page. In addition, the OSG Release Process includes a set of variables that should be used in all documents that refer to the items represented by those variables. Finally, there is a set of command-like variables that allow you to easily create status tables for documents of interest to you. These variables are described in the following sections.

hand A required variable must be assigned a value, while an optional variable may be left blank!

hand A static variable describes a fixed property of the document, while a dynamic variable is part of the document process and may change!

Document Owner Variables

The following variables may be set by the Owner of the document.

Variable Description Comment
OWNER The Twiki username of the owner of the document. required, static
INCLUDE_REVIEW Specifies if the document should be reviewed before release. required, static
INCLUDE_TEST Specifies if the document should be tested before release. required, static
REVIEWER The Twiki username of the reviewer chosen for the document. optional, dynamic
REVIEW_READY Marks a document ready to be reviewed for the reviewer. required, dynamic
TESTER The Twiki username of the reviewer chosen for the document. optional, dynamic
TEST_READY Marks a document ready to be tested for the tester. required, dynamic

The following set of variables are set by the Owner but refer to the document itself.

Variable Description Comment
DOC_TYPE The type of this document as defined in Document Types optional, static
DOC_ROLE The role of the intended reader of this document as defined in Document User Roles optional, static
DOC_AREA The document organizational area to which this document belongs as defined in Document Areas optional, static

Document Reviewer Variables

The following variables may be set by the Reviewer of the document.

Variable Description Comment
REVIEWER The Twiki username of the reviewer chosen for the document. optional, dynamic
REVIEW_PASSED Defines the current status of the review process. %IN_PROGRESS%, %YES% for passed, %NO% for failed

Document Tester Variables

The following variables may be set by the Tester of the document.

Variable Description Comment
TESTER The Twiki username of the tester chosen for the document. optional, dynamic
TEST_PASSED Defines the current status of the test process. %IN_PROGRESS%, %YES% for passed, %NO% for failed

HTML Comment Containing the Content Management Control Variables

Please include the following HTML comment at the bottom of those pages that should be part of the official OSG documentation.

<!-- CONTENT MANAGEMENT PROJECT
############################################################################################################
DOCUMENT OWNER
===================

   Thank you for claiming ownership for this document! Please fill in your FirstLast name here:
   * Local OWNER          = 

   Please define the document area, choose one of the defined areas from the next line
   DOC_AREA = (ComputeElement|General|Integration|Monitoring|Operations|Security|SmallSite|Storage|User|VO)
   * Local DOC_AREA       = 

   define the primary role the document serves, choose one of the defined roles from the next line
   DOC_ROLE = (Any|Developer|Documenter|Scientist|Student|SysAdmin|VOManager)
   * Local DOC_ROLE       = 

   Please define the document type, choose one of the defined types from the next line
   DOC_TYPE = (HowTo|Installation|Knowledge|Navigation|Planning|Team|Training|Troubleshooting)
   * Local DOC_TYPE       = 
   
   Please define if this document in general needs to be reviewed before release ( %YES% | %NO% )
   * Local INCLUDE_REVIEW = %YES%

   Please define if this document in general needs to be tested before release ( %YES% | %NO% )
   * Local INCLUDE_TEST   = %NO%

   change to %YES% once the document is ready to be reviewed and back to %NO% if that is not the case
   * Local REVIEW_READY   = %NO%

   change to %YES% once the document is ready to be tested and back to %NO% if that is not the case
   * Local TEST_READY     = %NO%

   change to %YES% only if the document has passed the review and the test (if applicable) and is ready for release
   * Local RELEASE_READY  = %NO%


DOCUMENT REVIEWER
======================

   Thank for reviewing this document! Please fill in your FirstLast name here:
   * Local REVIEWER       = 
  
   Please define the review status for this document to be in progress ( %IN_PROGRESS% ), failed ( %NO% ) or passed ( %YES% )
   * Local REVIEW_PASSED  = %IN_PROGRESS%


DOCUMENT TESTER
====================

   Thank for testing this document! Please fill in your FirstLast name here:
   * Local TESTER         = 
  
   Please define the test status for this document to be in progress ( %IN_PROGRESS% ), failed ( %NO% ) or passed ( %YES% )
   * Local TEST_PASSED    = %IN_PROGRESS%
############################################################################################################
-->

Release Variables

There are a set of variables that are to be used when referring to various constants like the current the current software release number. These variables are described in Release Variables?.

Tracking documents for which you have some responsibility

There are a set of tools (command like TWiki variables) to track various official documents in the OSG TWiki. These can be used to create tables on your home page (typically Main.FirstLast) that will list documents for which you are the Owner, Reviewer, or Tester. Variables also exist for Area owners of documentation. Complete information on these tools can be found in Tracking Documents.

Document Formatting

There are a set of formatting standards, methods to structure composite documents, and very useful formatting tools that automatically format certain types of information that are described in Document Formatting.

Responsibilities

The responsibilities of the Documentation Architect and the Document Owners, Reviewers, and Testers are explained in the following sections.

Documentation Architect Responsibilities

The OSG Documentation Architect is responsible for establishing and maintaining the overall architecture, standards, processes, and guidelines for documentation provided by OSG for its members. More detail can be found in DocArchitectResponsibilities.

Document Owner Responsibilities

See writer advice for some general advice on writing.


Each document in the Official OSG Documentation TWiki must have an Owner. Document Owners should also be familiar with the responsibilities of the Reviewers and Testers.

The owner of a document should have knowledge about the topic of the document and is responsible for:
  1. Creating the document (if it doesn't exist) in either the Documentation Web (for general, non-release dependent documents) or Release3 Web (for documents that tend to change with releases). When creating the document, a template can be chosen on the topic creation page via a drop down list. See document types for a description of the provided templates. After creating the document, you will be in the editor with the new page and you can edit the contents.
  2. Inserting and updating the Content Management Variables in the HTML block at the end of the document. The templates all contain the Content Management Variables but the values will need to be updated.
  3. Testing or ensuring that testing is done on the software and version the document applies to.
  4. Updating/improving the document. [For minor updates, you can just edit the released document. For an extensive rewrite, you may want to create a copy in a team web and replace the official document (using copy and paste) after you have had the new one reviewed.] Updates should be done when:
    1. Errors are discovered (typically by document users or the Integration or Documentation Teams).
    2. Users make comments in the document noting problems or improvements needed.
    3. Software or other changes make the document out of date.
    4. A new OSG release requires a change in the document.
    5. The document is identified by the Ongoing Evaluation/Improvement Process as needing improvement (up to 2 times a year).
  5. Working in collaboration with the Reviewer of the document to resolve issues identified by the Reviewer after each significant update. Set the REVIEW_READY variable to %YES% and the REVIEW_PASSED variable to %IN_PROGRESS% and email the reviewer to initiate the review.
  6. Working in collaboration with the Tester of the document to resolve issues from a test of procedures (if applicable). Set the TEST_READY variable to %YES% and the TEST_PASSED variable to %IN_PROGRESS% and email the tester to initiate the test.
  7. Setting the RELEASE_READY variable to %YES% when you and the reviewer [and Tester] are satisfied with the document.
  8. Notifying the Document Architect if unable to continue to fulfill the responsibilities of the Owner.

Document Reviewer Responsibilities


All documents in the official OSG Documentation TWiki have a Reviewer during their creation or update process.

The reviewer of a document should have knowledge about standards and format for the type of document being reviewed and is responsible for:
  1. Performing a review (when the Owner marks the document as REVIEW_READY and REVIEW_PASSED is IN_PROGRESS) and correcting or noting issues (via email or the document Comment block) for the Owner. The review should verify that the document:
    1. Contains the relevant sections specified in the template for the relevant document type. See Document Types and Templates. Only applies if a template is provided.
    2. Sections and content conform to the formatting standards for the relevant document type. See DocFormattingRules.
    3. Is clearly written and can be understood by a reader with a suitable level of expertise.
    4. Has or refers to a diagram of the appropriate architecture (if applicable).
    5. Is technically accurate and complete (the Reviewer is not responsible for actually testing a procedure).
    6. Contains no typos or wording errors.
  2. Updating the REVIEW_PASSED variable in the HTML block at the end of the document. Do this by editing the document using the Edit link at the bottom of the page.
  3. Working in collaboration with the Owner to ensure the issues you identify are resolved in the document.
  4. Doing a final review when you, the Tester, and the Owner agree it is complete and updating the REVIEW_PASSED variable.
  5. Notifying the Document Architect if unable to continue to fulfill the responsibilities of the Reviewer.

Document Tester Responsibilities


Procedural documents in the official OSG Documentation TWiki should have a Tester.

Each installation or procedure document in the OSG Documentation TWiki should be tested. The purpose of the test is to check if the documented procedures yield expected results when carried out. The Owner of a document will typically request involvement of a Tester when a document needs tested. A document needs to be tested:
  1. After it has been created.
  2. After major changes to the document have been made.
  3. Before major releases.
The Tester should preferably be a person that is not:
  1. The developer of the software or procedure described in the document.
  2. The Owner of the document.
The Tester of a document should only have a general knowledge about the topic of the document. To follow the instructions of the document, the tester must have access to facilities needed for the test (e.g. a local site resource or ITB resource). The Tester is responsible for:
  1. Performing a test (when the Owner marks the document TEST_READY and TEST_PASSED is IN_PROGRESS) of the instructions on the software and version the document is meant to be used with and noting any problems or anomalies.
  2. Updating the TEST_PASSED variable in the HTML block at the end of the document. Do this by editing the document using the Edit link at the bottom of the page.
  3. Working in collaboration with the Owner of the document to resolve issues from a test of procedures.
  4. Doing a final test (if necessary) after the issues are resolved to verify the procedure presented the document can be performed successfully and updating TEST_PASSED variable.
  5. Notifying the Document Architect if unable to continue to fulfill the responsibilities of the Tester.

HELP NOTE
The roles of the Reviewer and Tester are different! The Reviewer is only responsible to check documents for their readability, logical structure, and conformance to standards, while the Tester must apply the procedures as described in the document.

Comments

-- JamesWeichel - 13 Jan 2010

Topic attachments
I Attachment Action Size Date Who Comment
jpgjpg ProcessDiagram.jpg manage 40.2 K 28 Apr 2010 - 20:22 JamesWeichel Process Diagram
Topic revision: r47 - 15 Feb 2012 - 20:58:59 - KyleGross
Hello, TWikiGuest!
Register

 
TWIKI.NET

TWiki | Report Bugs | Privacy Policy

This site is powered by the TWiki collaboration platformCopyright by the contributing authors. All material on this collaboration platform is the property of the contributing authors..