USG Documentation Process and Standards

This page is intended to document USG members' criteria and preferences for documentation as well as the process used to create documentation that meets those criteria. For information on the process behind the devlopment of these documentation standards, visit the TwikiDocumentationSurveyAnalysis page.

The main purpose of this page is to train USG technical writers. However, anyone who finds it interesting is welcome to read it. After initially reading through this document, the technical writer may be interested in frequently revisiting these sections: General Template and Standard Application Steps.

Initial Version

1. Interview: 8 technical things to know
2. Interview: help the technical writer flesh out the details
3. First draft
4. Apply documentation standards
5. Have another techie try it out

Refined Version

Identify the Topics

• Obtain topics from management on what to document and from which technical staff person.

Contact Staff Member

• Then, proceed to email technical staff person requesting documentation for relevant topics, suggesting ways to help get them started.

Flesh Out the Details

Tasks

Troubleshooting

Problem Scenarios

• Symptoms, e.g. error messages

Diagnosis Questions

• Questions to ask the client requesting service: lab`s room number, student ID, machine name and version, date and time when the problem occurred

Possible Causes

• A server, an app, etc.

Possible Solutions

• Rebooting and other solutions
• Detailed steps including scripts and commands if applicable, similar to the content of S.T. Thoroughness is very important: if a few key details are missing, that could render the entire document worthless and the reader would have to figure out the solution from scratch.
• Warnings

Success Indicators

Deployment

Software Installation and Configuration

• Locations of the software and the source code; locations of the download files if applicable
• Credentials: open source? license location?
• Authors: was it created by internal staff?
• Admins: who is responsible?
• Programming language
• How to update it
• Detailed how-to articles with detailed steps
• Info about deployment is not needed because it only needs to be done once

Testing

Create a First Draft

• Record the technical information that has been relayed

Apply documentation standards

Standard Application Steps

Motivation

To see further motivation behind the steps below, click here https://cs.uwaterloo.ca/twiki/view/CF/TwikiDocumentationSurveyAnalysis#Organization

Step 1 Create an introduction:

• Create a section at the top of the page that acts as an overview of the system (e.g. Markus). Some information that can be included are:
  • what functions does it provide
  • who uses it
  • which courses use it
• See the Own Cloud page for an example
• The cover page includes a link to the detailed and technical Twiki page about the system.
• Make the Twiki word (mashed caps) specific for disambiguation. For example, "cs.uwaterloo.ca/twiki/view/CF/OwnCloud#Windows_client" is better than "cs.uwaterloo.ca/twiki/view/CF/#Windows_client"

Step 2 Organize the content into sections with the following titles: 1) problem scenarios, 2) diagnosis questions, 3) possible causes, 4) possible solutions, 5) success indicators, and 6) deployment

Step 3 Add "Note" and "Warning" where applicable to make the documentation easy to scan:

Step 4 Break long sentences into numbered or bulleted lists with one action in each line:

Step 5 Add any related links from the CS website:

• Use "site: cs.uwaterloo.ca" to Googles-search for other documents about the system. Place in the new documentation references to all those other documents.
• Browse through the USG Twiki website. In all the related documents, place references to the new documentation.
• Place next to _each_ hypertext link a descriptive sentence. This sentence should describe the context (primary and secondary audience) and the purpose of the documentation being linked to. The primary audience is USG staff, while the secondary audience should be anyone who is interested. (See the upper left hand corner of the CF page.)
• Make the hypertext link specific. E.g. Instead of having 5 links named "Markus", name them "Markus - ISG's detailed notes" and "Markus - USG", etc.

Step 6 Synopsis

• For each Twiki page, provide a 2-5 sentence summary of the content. This acts as the "rhetoric of arrival" so the readers can confirm that they are on the right page.

Step 7 Table of Contents

• Use the &37TOC&37 Twiki function to place a table of contents after the synopsis. This is because tables of contents can be very long.
• To learn more about the % T O C % function, click "Edit" at the top of the page, and then click "More formatting help" at the bottom.
• Also, experiment with Twiki functions in the sandbox: https://cs.uwaterloo.ca/twiki/view/Sandbox/WebHome

Step 8 Rearrangement

• On the webpage, place troubleshooting information above deployment information.

General Template

The following is an even shorter summary of the desired content and format for documentation. It is designed to be cut and pasted to quickly create documentation that satisfies the organization criteria.

Trouble-shooting

Problem Scenarios

• _How to Extract this from the S.T._ :
• Q: How to see where one problem ends and the next one starts?
• A: Closer dates on the S.T. items probably indicate that they describe the same problem. That is a last resort, though. A more accurate indication is the actual content of the S.T. item.
• The "subject" field
• The "keywords" field
• The "service" field
• The "type of work" field
• The "machine name" field
• The "requesters" field (course/client affected)

Diagnosis Questions

Possible Causes

Possible Solutions

Final Solution

Details: scripts and commands Warnings Success Indicators See also:

• _How to Extract this from the S.T._ :
• The "see also" field
• The "ancestors" field
• The "dependencies" field

This section was last updated on:

Non-emergency Tasks

What is __ (system)?

TOC

Software, source code, and download files location

Licensing

Admins: who is responsible? Motivation: This information will help the readers prioritize the parts of the documentation to read.

• _How to Extract this from the S.T._ :
• The "activity" field
• The "responsible" field and the "owner" field

Programming language

How to update

(Steps)

1. Heading (Clearly indicating why we want to do this step. E.g. "Add Students") 2. Heading 3. Heading ...

See also :

• How to Extract this from the S.T. :
• Include the S.T. URL

Section's last update : _How to Extract this from the S.T._ :

• As a rule of thumb, use the date of the last entry in the particular S.T. item.

Sample Documentation

Some Twiki pages that have been created in light of the above standards are:

• https://cs.uwaterloo.ca/twiki/view/CF/MediaWiki

Have another techie try it out

Step 1.

• Use this CSCF document called "Who Does What" to determine other staff members whose responsibilities require the knowledge that you are trying to document: http://www.math.uwaterloo.ca/mfcf/internal/whodo/
• If the above link becomes broken, simply Google "CSCF Who Does What"

Step 2.

• Contact the appropriate personnel to request them to test the new documentation.