THIS PAGE HAS BEEN MIGRATED: https://uwaterloo.atlassian.net/wiki/spaces/CSCFINF/pages/44209242230/CSCF+Documentation+Standards

Standards for Internal Documentation

Our internal documentation is that documentation we produce to help us provide computing support to our clients, that we don't expect our clients to read.

We document our standards and procedures in order to

• have a minimum standard of service
• provide consistent service
• facilitate redundancy by making information learned by one available to others
• make our work known to other support groups so that they may benefit by not having to duplicate the work required to discover problem solutions
• encourage standard approaches to support
• encourage a reasoned approach to problem solving

Our standards for internal documentation are:

• documentation is WWW based (with some security exceptions)
• a common starting point for all internal documentation; a single table of contents and index (i.e. searchable)
• practical to update
• form and production is kept simple. Wiki's have that characteristic, as do simple HTML pages.
• world readable documentation, access is restricted only for those parts that need to be private (passwords, license codes, etc.)
• documentation should be in shared space, not personal space, so that it does not need to be retrieved manually if a staff person leaves

Details

WWW Based Documentation

Documentation we create, that isn't required to be in some specific form or location due to software constraints (e.g. "man" pages), or security concerns, is expected to be accessible from the WWW. For secure documents, the WWW documentation may simply refer the reader to where to find the documents.

Documents that can't be quickly and conveniently viewed by all common browsers should be avoided where possible. In practice that means use HTML (or something which is provided as HTML by the WWW server, e.g. Wiki pages); avoid PDFs and Word documents when composing online documentation. They are, however, useful in producing a printable form of documentation.

A Common Starting Point

It should be possible to find needed documentation by starting at a single place, and searching from there. We're now using

https://www.cs.uwaterloo.ca/twiki/view/CF

World Readable Documentation

We only restrict access to documentation where it's perceived that making it public would be detrimental to security or privacy. Some of the few such examples are documentation about access to secure systems, and minutes of meetings involving confidential discussions.

Where to Put Documentation

• www.cs.uwaterloo.ca/cscf
  • This is for documentation that is expected to be read our clients; 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 significant changes/additions
  • all top-level pages should follow the "Common Look and Feel" (CLF) rules; it's still debatable whether this rule need apply to every single page, e.g. for various machine generated statistics.
  • files are managed using RCS in the underlying Unix system, unless the pages are generated from some other source.

• CF Twiki
  • this is for our internal documentation
  • although intended for use by computing support staff, it's viewable by the general public, including Google
  • "draft" documents are acceptable, some documentation is better than none
  • good organization is encouraged, but documents are easily moved/referenced later, so don't let it slow you down
  • non-HTML files can either be attached to the Wiki or stored in edocs and referenced here

• CFPrivate
  • only viewable by CF Staff
  • for the parts of the documentation above 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
  • non-HTML files can either be attached to the Wiki or stored in edocs and referenced here

• ST
  • we track our work here, so new procedures often end up being described here
  • detailed one-of procedures can be described here
  • if a procedure is to be used more than once, then a more formal description in the internal documentation is appropriate
  • attachments can be referenced in EDocs in the directory edocs/rtattach/ST# (see below)

• Inventory
  • details about anything that has a barcode (that we add), or anything that deals with DNS, as the inventory interface is growing to facilitate the workflow involved with OS instances, which includes maintenance of DNS and DHCP information.

• EDocs
  • www.cs.uwaterloo.ca/cscf/internal/edocs/
  • for sharing among multiple users in CSCF
  • not visible beyond CF staff
  • available via a Samba share: smb-files.cs.uwaterloo.ca\edocs
  • rtattach/
    • binary files that will be referenced in ST or that can be
  • machines/
    • information, over and above that found in inventory, that is needed/useful in providing service
    • required for any new (virtual) machine
  • printers/
    • basic support information about specific printers
    • required for any new printer
  • ...

• asimov.cs (Application Server)
  • OS image files
  • software installation files
  • notes/documentation relating to those items, although they should be findable starting with the internal documentation described above.

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 the internal support documentation.

• your own workstation
  • certainly, documentation can be developed here and then copied/moved to one of the above locations

• www.math.uwaterloo.ca/mfcf/internal
  • deprecated

• www.cs.uwaterloo.ca/cscf/internal
  • deprecated for text documents, see ST and EDocs above.

The Transition

Now that MFCF has finally/formally said that they won't be collaborating in technical documentation, we need a plan for merging:

• http://www.math.uwaterloo.ca/mfcf/internal
• http://www.cs.uwaterloo.ca/cscf/internal

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

This may be best done by first determining what organizational guidelines are best suited for the result.

In the hope of encouraging collaboration, we have CSCF-specific pages and MFCF-specific pages (the latter having never been used). The distinction between CSCF-specific pages and general pages proved to be a bit fuzzy. Now that collaboration isn't a constraint, merging the CSCF-specific pages with the rest seems appropriate.

That may be the extent of the change we need, but it would be good if we could determine guidelines that would help people understand where to find information, and where to put new information.

Comments.

This proposal does not (yet) provide for the enforcement of change management on pages like internal guidelines nor does it deal with dynamically created pages like those referenced from https://cs.uwaterloo.ca/cscf/internal/infrastructure/inventory/

See also: EDocs.