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

Topic revision: r3 - 2013-02-15 - DrewPilcher
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback