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