Documentation
CPTE 433
John Beckett
1/20
What To Document
• Whatever you want to forget how to do
• Whatever you want somebody else to be able
to handle
• Whatever might be expensive if it’s done
wrong
• The more you dislike a task, the more
important it is to document it!
2
What’s in Documentation
The most important three things you
need to think about when writing
anything are:
•Audience
•Audience
•Audience
• Title – one line, please
• Author & date
• What this is good for
• Context needed for this to work
• How to do it
• How to make sure you got it right
Make a template so you don’t forget!
3
Proofing a Document
•
•
•
•
•
Walk through the process, actually doing it
Enter corrections
Have someone else critique it
Have someone else use it
Does it pass the “duct tape test”?
– Duct tape tying your hands / don’t touch
keyboard/mouse
– Duct tape over your mouth…
4
“Quick Guide”
• Summarize steps
• Example: the most common case
• The quick guide should be good enough for
anybody who has done it, to do it again
• Another type: The new user who is too lazy
to read “the manual.”
• Making a quick guide is a great way for you to
learn the product yourself.
5
Sources for Documentation
• Annotated screen shots
– Insert commentary
– Draw arrows
• Command line capture
– Commentary in another font
• Email
– Wonderful way to build a FAQ
– May have to edit so that the questioner doesn’t look stupid
• Make them look the way you wish your customers looked, it’s your
chance!
• Ticketing System
– Were there incidents provoked by somebody not knowing
something?
6
Checklists
• Tasks to be done for each new hire
• Tasks for termination
• Installation for each OS used at a location
– Hmmm…didn’t you automate that?
• Process for archiving and off-site storage
• Securing the OS before deployment
7
Documentation Storage
• Common repository
• Common format so everything fits in the
repository
– Scan external documents in
– Turn Web pages into PDFs
• Indexing system
– A data base may be indicated
8
Source Code Control
• Source code control/tracking systems can help
you find out what was changed
• …and when
• …and by whom
• …and why
9
Wiki
•
•
•
•
Collaborative documentation system
Peer review
Commonly understood by techies
Placeholder pages indicate need for more info
or for review
10
Searching
• Find a full-content search system
• Don’t write it yourself
– http://www.google.com/coop/cse/
11
Getting Buy-In
• Make your documentation available to others
• Wiki it so it can be edited by others
• Use it to help others
• They’ll take it over!
12
Content Management System
• Like a Wiki, only more oriented to control
• E-class is a CMS
13
Culture of Respect
• “NPV” approach
– No negative value assigned to people
– The point is what is done for the group, whoever
that is
• Public appreciation
• If possible, editing should be done by the
originator
14
Additional Documentation Uses
• Self-help desk
– User can research the problem history
– User can submit a ticket
– User may withdraw a ticket with no penalty
• How-To docs
– Great for processes specific to your facility
– Wiki can let customers edit so they can understand
• FAQs
– Part of the Wiki/search system
15
Reference Lists
•
•
•
•
•
Vendors & contact info
Serial numbers and asset tags of hardware
License keys, number of users for s/w
Compatibility lists (less of a problem now)
Employee directory – manual or automatic from
corporate database
• Local facilities – restaurants, taxi companies, etc.
• Tips when visiting each office location
• Whom to notify for each need
16
External Specifications
• ISO 9000 – specification for quality
procedures (no guarantee of quality)
• OSHA
• Sarbanes-Oxley
17
Technical Library
• Documents from vendors should be centrally
located
– Networking gear
– Motherboards
– Peripherals
• Scrapbook
– Floor layouts of your building(s)
– Location of networking outlets
18
Off-Site Links
• Make sure the referring machine doesn’t give
away secrets!
• Use an anonymizing system to pull in those
pages from elsewhere.
19
Using Icons
• Icons are an attempt to communicate meaning
without language
• Icons rely on culture
– Which is itself a form of language
• Hence: Some people will fail to understand
any specific icon!
• Cure:
– Include word in icon
– Use pop-up messages to explain icons
20