Documentation Standards

• Note: this is a proposed set of standards for documentation within CSCF and should not be considered official at this time
• Comments welcome
• Lawrence Folland 2006/02/09

General Principles

• documentation of policies and procedures is a Good Thing™
• wherever possible, documentation should be publicly visible
• private documentation should be limited to only those parts that need to be private (passwords, license codes, etc.)
• documentation for the organization should be in shared space, not personal space, so that it does not need to be retrieved manually if a staff person leaves
• some documentation is better than no documentation (not everyone may agree with this philosophy)
• documentation aimed at clients external to CSCF should be particularly checked for spelling, grammar and formatting

Where to put documentation

• www.cs.uwaterloo.ca/cscf
  • This should be for documentation that is expected to be read by clients outside of CSCF, including CS faculty, students and other CS staff
  • anything here is accessible to Google
  • this should be carefully organized and the appropriate manager(s) should be notified of any changes/additions
  • all pages should follow the "Common Look and Feel" (CLF) rules
  • files are managed using RCS in the underlying unix system

• CF Twiki
  • This is for any internal documentation that is acceptable to be viewed by the general public, including Google
  • "draft" documents are acceptable and appropriate - the Twiki encourages collaborative development
  • some consideration to good organization is encouraged, but documents are easily moved/referenced later, so don't let it slow you down
  • notes intended for external clients can go here, but should be considered for moving to the official website eventually
  • binary files that are publicly viewable can be added as attachments to a wiki page

• ST
  • notes relating to requests should go into ST
  • detailed procedures can be described here
  • consider organizing procedures into a more formal document in the Twiki or the web space
  • attachments can be referenced in edocs in the directory edocs/rtattach/ST# (see below)

• EDocs
  • www.cs.uwaterloo.ca/cscf/edocs
  • binary files that will be referenced in ST or that can be shared amongst multiple users in CSCF
  • not visible beyond CF staff
  • available via Samba share: smb-files.cs.uwaterloo.ca\edocs

• CFPrivate
  • only viewable by CF Staff
  • for documentation that should not be publicly available
  • if not sure, you can start with a document here (that way it won't end up in Google) and then move it after discussion with your manager (Note: I realize that not everyone may agree with this philosophy)
  • electronic documents can either be attached to the wiki or stored in edocs and referenced here

• cscf.cs
  • not sure ... comments, anyone?
  • personal files?

• asimov.cs (Application Server)
  • image files
  • software installation files
  • notes/documentation relating to those items

Where not to put documentation

• www.cs.uwaterloo.ca/~userid
  • this should be for personal information/use
  • if you have organizationally-useful information here, consider moving it to one of the places above

• your own workstation
  • certainly, documentation can be developed here and then copied/moved to one of the above locations
  • again, consider developing docs on the Twiki and then moving it

• www.cs.uwaterloo.ca/cscf/internal
  • by the definition above, the main web space is for external viewing (Note: debatable point)
  • possible suggestion: make this accessible to CF staff only, so that web pages can be developed here for private use, if desired
  • downside of the above: not searchable by Google

• www.math.uwaterloo.ca/mfcf/internal
  • deprecated (again, my suggestion)
  • some effort needs to be made to move/copy material into the wiki and implement an organization on the wiki that works reasonably well for everyone

-- LawrenceFolland - 09 Feb 2007