Documentation Standards 2022

A lot has changed since the original creation of the DocumentationStandards Those "standards" were never fully adopted and agreed upon. This page will provide a list of current and potential sources of documentation and then a list of types of documentation and/or particular needs. Finally, we will want to specify which documentation tools are to be used for what types of documentation.

Documentation Locations and usage

CF Twiki

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

This is a publicly available set of Twiki pages where (primarily) CSCF staff have provided an extensive and wide variety of notes. There is a lot of valuable information here, but there is also a lot of out-of-date information. It needs extensive "gardening". These notes are not necessarily "pretty" for client consumption, although some are.

CFPrivate Twiki

• https://cs.uwaterloo.ca/twiki/view/CFPrivate/WebHome

This is privately viewable and editable by CSCF and MFCF staff only. In practice, it is only used by CSCF staff. This is for documentation that is not intended for clients or the public to see, including detailed machine notes, even passwords. Also used a lot for meeting minutes for various working groups and staff meetings. Machine Notes, typically linked in inventory, are stored here.

CSCF WCMS pages

• https://uwaterloo.ca/computer-science-computing-facility/ or
• https://cs.uwaterloo.ca/cscf

These are the official web pages for CSCF. They include a skeleton of service pages which really need to be fleshed out. Information about staff is linked to the main CS pages. There are some news and events notices. We have a few "how to guides and tutorials"

CSCF Internal web pages

• https://cs.uwaterloo.ca/cscf/internal/

These are originally from the old CS web server. These are primarily used by the Infrastructure group for their documentation: https://cs.uwaterloo.ca/cscf/internal/infrastructure/

Out-of-band CSCF Web server

• we have discussed setting up an out-of-band CSCF web server that would not be dependent on any network file systems. Documentation stored here should be available when other sources may not be (eg: the Twiki)
• this is in the process of being setup but is not ready, as far as I know

eDocs

• https://cs.uwaterloo.ca/cscf/internal/edocs/
• \\smb-files.cs.uwaterloo.ca\edocs

This is a network file share, accessible via Samba or via the web link above. As a group share, this allowed all CSCF staff to access a common set of files. Machine Notes used to be stored here. There are folders for documentation, a large collection of eBooks, RSG files (all of the IncomingGrads spreadsheets)

RT

• https://rt.uwaterloo.ca/

RT is our primary tool for recording tickets and the work done on them. While it is essentially only used while working on a task, it is a great store of information about our work. Formerly we used ST. That information is still there, but we are no longer updating those tickets.

• ST: https://cs.uwaterloo.ca/cscf/internal/ST/

Inventory

• https://cs.uwaterloo.ca/cscf/internal/inventory/web/inventory/

Those tool is used to track all of our assets. It has links into RT, InfoBlox (DNS management), ONA and Netmon (switch managment), OpenDCIM (rack managment). Inventory records include links to Machine Notes (generally in Twiki) to describe how to administer a machine.

Teams

• CSCF Team: https://teams.microsoft.com/l/team/19%3a729945c461eb4b83a08c350991aae7b6%40thread.skype/conversations?groupId=e3abbaa0-ade4-435a-a166-1e8349e9e65e&tenantId=723a5a87-f39a-4a22-9247-3fc240c01396

Some groups use Teams to store files, but we have primarily used Teams for discussion

Sharepoint

• https://uofwaterloo.sharepoint.com/sites/math-cs/default.aspx
• CS and CSCF mostly don't use Sharepoint. However, there is a fairly under-used out-of-date CS Sharepoint site (see above)

Twitter

• @cscfhelp
• CSCF Help Desk maintains a Twitter site for emergency notifications
• Documentation (ish): https://cs.uwaterloo.ca/twiki/view/CF/HelpDeskGuide#CSCFHelp_Twitter_cscfhelp

Confluence Knowledgebase

• General: https://uwaterloo.atlassian.net/wiki/spaces
• IST KB: https://uwaterloo.atlassian.net/wiki/spaces/ISTKB/overview

We in CS/CSCF don't use Confluence at this time. However, note that a lot of other faculty support groups do use Confluence (eg: ACO, MAD)

Types of documentation and needs

Public information about CSCF

• general information about CSCF is typically stored in the WCMS site

Client information and help pages

• This is probably one of the two most critical types of information - pages to help our clients.
• The primary site for this should be our CSCF WCMS pages, but there is very little information there
• the other site with a lot of information (both current and out-of-date) is the CF Twiki
• this is a key are we need to consider

Internal information pages

• These are pages that we need to document our own internal procedures - from staff duties to technical procedures
• this is currently split between the CF and CFPrivate Twikis, and the cscf/internal web pages
• Twiki pages are often very out-of-date. Also, there is so much information, it can be hard to find what you're looking for
• there is some very old information in eDocs, but mostly that is not used
• one need we have discussed is having information available when all else is down. Thus the desire for an out-of-band server

What we need to decide

• Should we continue with the Twiki. If so, how will it get updated?
• Should we consider Confluence?
• will we setup the out-of-band server? Will it replace cscf/internal? Should it house the inventory database? and store Machine Notes?
• we should really update our Services pages for clients on the WCMS. This might best be done by assigning ownership for each service. There was a spreadsheet developed when we first created the WCMS that may have that information.

-- Lawrence Folland - 2022-03-31

Comments