CF Web>UserSupport>SystemAdministratorDocumentationTemplate (2013-07-17, DrewPilcher)

EditAttach

The Name of the Page

A high-level description of the system

The Name of the Page

System Specifications

Hardware

Key hardware information related to the system. For example:

Some examples:

Machine's name: markus002.student.cs.uwaterloo.ca
- May be moved to another server in the winter term
Server's name:
- Server1
- Server2

Software

Key software information related to the system. For example:

For example:

Server OS: Ubuntu 12.04 Server
Database type: SQLite Version 3.7.16.2
Tables: Users, Assignments, Courses

Authentication and Authorization Information

Many systems demand authentication before they can be managed. List the information required to gain access to the system. Please do not put passwords on this page. This page will be public and accessible by Google.

People

People that may need to be contacted when working with this system

Administrator: [Name]
Point of contact (expert): [Name]
Stakeholders:
- CS 100
  - Requires system for use in assignments
  - Usually requires approximately user 200 accounts
  - Primary contact: Arthur Conan Doyle (ext. 22790)
- CS 136
  - Requires system for assignments
  - ...

Terminology

Unique terminology that might be required while performing tasks on this system. For example:

Definitum
- In a definition the word being defined is the definitum
- Is a fancy word that nobody ever really uses
MarkUs
- A marking system in which students can submit their code and faculty can provide feedback and assign grades
- Originates from the University of Toronto

Guides to the Completion of Scheduled Tasks

Some tasks must be completed on a regular basis. List the scheduled tasks from least frequently recurring to most frequently recurring. Each one must have a detailed guide on how to go about completing the task and how often/when the task must be completed. Try to be as detailed as possible.

For example:

Between Every Term

Empty the database

Keeps things clean and organized

Log in to the database.
- This is a secure connection
Run the purge command
log out
- The logout button is at the top-right of the page
Try to make a query to the database. If it returns an error, you are good to go.

Another Example, also completed between every term

This example will help you understand

Do this
Do that
Now do something fancy

Guides to the Completion of Common Requests

This section outlines the guides to completing tasks that are commonly requested by stakeholders

Heading with a very high-level description of the request

Description of step
- Details and notes about how to complete the step
- Details and notes about how to complete the step
...

Set Up an Exam

Log into the system for setting up exams
- located at insert_url
- use your WatIAM credentials
...

Common Failures/Bugs & Troubleshooting

This section outlines some issues that have been known to occur with the system, along with details on how to fix them and when they occur.

Each section should be formatted like so:

A level-3 heading that identifies the issue

Paragraph text to explain the symptoms that would be observed when the issue exists.

Optional paragraph text that describes the potential causes of the issue.

A level-4 heading that says, "How to Fix the Issue"

A series of steps to fix the issue
- Formatted as an ordered list of steps
- If the fix is really simple, describing it in a small paragraph will suffice instead of using the list format

Current Discussions Related to the System

Some systems have important long-term changes that are being discussed. If needed, a summary of each discussion may be included here.