This document provides guidance on creating effective documentation for system administrators. It discusses why documentation is important, what types of information should be documented, general guidelines for documentation, and tips for specific documentation challenges like procedures, lists, tables and FAQs. The document encourages establishing structure, templates and regular updates to documentation. It also provides examples of effective documentation elements. The overall goal is to help system administrators understand the value of documentation and improve their documentation practices.
This document provides guidance on creating effective documentation for system administrators. It discusses why documentation is important, what types of information should be documented, general guidelines for documentation, and tips for specific documentation challenges like procedures, lists, tables and FAQs. The document encourages establishing structure, templates and regular updates to documentation. It also provides examples of effective documentation elements. The overall goal is to help system administrators understand the value of documentation and improve their documentation practices.
This document provides guidance on creating effective documentation for system administrators. It discusses why documentation is important, what types of information should be documented, general guidelines for documentation, and tips for specific documentation challenges like procedures, lists, tables and FAQs. The document encourages establishing structure, templates and regular updates to documentation. It also provides examples of effective documentation elements. The overall goal is to help system administrators understand the value of documentation and improve their documentation practices.
This document provides guidance on creating effective documentation for system administrators. It discusses why documentation is important, what types of information should be documented, general guidelines for documentation, and tips for specific documentation challenges like procedures, lists, tables and FAQs. The document encourages establishing structure, templates and regular updates to documentation. It also provides examples of effective documentation elements. The overall goal is to help system administrators understand the value of documentation and improve their documentation practices.
System Administrator Janice Gelb Senior Developmental Editor Sun Microsystems, Inc. 1
About This Presentation
Most of you hate documentation. You hate having to write it, you hate the process of writing it, and you hate having to read it. This presentation tries to provide you with information and tips to change your opinion, or at least move you to grudging acceptance.
Presentation Contents Improving Your Documentation
Why Bother With Documentation?
What You Should Document General Guidelines Common Problem Areas
Improving Documentation for the Products
You Use Resources and References
Why Bother With Documentation?
This section describes some of the reasons why creating and maintaining documentation can benefit you and your organization
Why Bother? Documentation aids memory
Why Bother? Documentation: Can shorten downtime Helps you avoid repetitive research Enables you to go on vacation!
Why Bother? Saves you from having to answer repetitive questions
Why Bother? Documentation can make your customer interactions more productive: Providing templates promotes standardization for policies and procedures Distributing forms ensures that you receive the information you need for project plans and requests
Why Bother? Documentation can help with personnel issues: Makes new hire orientation and employee transitions more efficient Enables you to distribute information to dispersed geographic locations
Why Bother? The act of documenting a system or procedure can reveal missing information, procedural gaps, or inefficiencies
10
What You Should Document
So, what types of things
should you document?
11
What You Should Document
This list is not exhaustive but provides an idea of the types of things documented by many system administrators.
Project plans System documents Server logs Diagrams (such as system flowcharts, logical and physical network diagrams, and so on)
Network administration information Printing infrastructure Backup and restore process Feature and equipment requests User documentation 12
Project Plans Include the following information: What you need the server to accomplish Possible performance bottlenecks Plans to correct any issues noted For a simple installation, a project plan can be as simple as an outline and some diagrams. For a large-scale installation, you might need to divide the project into phases. 13
System Documents For each system document: Provide an overview
Hardware specs OS Library versions Build environment Partition table List of the IP interfaces and domain names that the machine services
14
System Documents (cont'd.)
Include an alphabetical list of each installed package and related details Installed version and installation date
Log location
Installed by
Application storage location
Purpose (short description)
Serial number and registration key
Package and download URLs
(developer's web site)
Prerequisites (other packages that
must be installed first)
Configure options (list of flags for
./configure or make, if applicable)
Patches applied
Application installation path
Path to configuration files
Notes Configuration files (full contents of all of the application's config files) 15
Server Logs For each server, document and keep updated information such as:
Hardware platforms IP addresses DNS names Dates of last update and patch installations Operating systems Running services Open ports Change log 16
Diagrams Data flow diagram System flowchart Don't mess with it
Yes
Does it work? You idiot
Does anyone know?
No
Hide it
Yes
No
No
Yes
You poor sucker
Can you blame someone else? Yes
Did you mess with it? Yes
No
Will you be blamed? No
Get rid of it
No Problem 17
Diagrams (cont'd.) Building diagram/floor plan Physical network diagram Logical network diagram
18
Network Administration Information
Call list contact information Vendor sheets (hardware and software) License information for software Maintenance contracts
19
Printing Infrastructure Consider including the following information: Server hosting the print device Printer make, model, and type Amount of RAM Duplex capability
Type of device connecting the printer to
the network and its firmware version Data transfer rate Types of paper supported
Methods to remotely manage the printer
Name, share name, and permissions used (for example, telnet) on the server for this printer Local superuser who can assist in IP address and configuration information troubleshooting and contact information
20
Backup and Restore Process
Document procedures for the backup restoration process: The steps necessary to restart a service List of important services that might need to be restarted Other information to help reduce the amount of downtime
21
Feature and Equipment Requests
Develop and distribute comprehensive request forms for new feature requests and new equipment orders Keep completed forms on file
22
User Documentation Help files Policies Manuals and web support for procedures
23
General Guidelines This section provides some general guidelines about producing and maintaining your documentation
24
If You're Starting From Scratch
Consider hiring or assigning a technical writer to author the initial wave of documents Investigate programs that can automatically extract and update hardware information Establish a safe and known place to store the documentation
25
Starting From Scratch (cont'd.)
Make a rough outline of the items you need to document. Consider these questions: What is every key piece of equipment and what does it do? Where are crucial files stored? What are your key processes? You might want to organize this investigation by department. How is each process completed? Why and when is it done? Who has key responsibility for internal business issues? Who are your key partners and contacts at other companies? 26
Starting From Scratch (cont'd.)
Determine whether the documentation will be available online, in print, or both
27
Set Up an Overall Organization
Network DNA (http://network-documentation.com) suggests the following organization: Non-network information - Vendors, supported locations, signatory authorizations, and so on Global network information - DHCP settings, DNS, mail providers, backup environment, and so on Network infrastructure Network devices Peripherals Software Administrative Service level agreements (SLAs) Diagrams
28
Structure Before You Write
Developing an outline helps ensure that your document will cover all necessary material. Consider creating templates and sample tables of contents for common items that your team needs to document
29
Keep Documentation Updated
Set specific intervals or milestones at which the documentation will be examined and updated if necessary
30
Keep Documentation Updated
Note issues that are currently unresolved but should be documented in a future version If you can track document access, schedule more frequently accessed documents for more frequent reviews Make sure that updating the documentation is a requirement in your relevant change or release management processes 31
Keep Documentation Updated
Encourage users to provide ongoing feedback
32
Content Tips Adjust your tone and content for your audience Include the reasons behind a design or decision as well as the result Use position titles rather than names Write out acronyms on first usage Provide a glossary for common corporate acronyms and terminology 33
Content Tips (cont'd.)
Use standard references and terminology for your platforms
34
Content Tips (cont'd.)
Avoid passive voice unless the actor is not important Awkward Some mistakes were made. Better The administration made some mistakes. Awkward The system copies the record to the database. Better The record is copied to the database. 35
Common Problem Areas
This section provides guidelines for the areas in technical documentation that are often the most difficult: Procedures Lists Tables FAQs Illustrations
36
About the Examples
Accompanying real-world examples show
how to apply the guidelines. All examples are reproduced verbatim and match the original formatting as closely as possible. The examples also contain other corrections and illustrate more precise writing and formatting, so you can also use them as a general guide.
37
About the Examples
The examples file is available at
http://lisa.usenix.org/janiceg/wtfm-examples.pdf
For best results, set the View->Page Display
options to Two-up and to Show Cover Page During Two-up.
38
Procedures When to Use
Procedures are probably the most difficult documentation structure to master. Use procedures when you need to document step-by-step instructions.
39
Procedures Guidelines
Do not bury steps in a paragraph
Make each step short and equivalent to one action Order and number all user instructions Place explanatory text in a paragraph underneath the action instruction
40
Procedures Guidelines (cont'd.)
List conditions, warnings, and hazards before describing how to complete the instruction Phrase steps in the imperative Awkward The window displays a field for you to enter the user name. Better Type the user name in the User Name field.
Ask a colleague in the target audience to test the
procedure
41
Procedures Guidelines (cont'd.)
Consider dividing a long task into related smaller procedures, and provide a numbered list to introduce the entire task Installing the Jetson Software Procedure
For More Information
1. Review the system requirements.
Jetson System Requirements
2. Choose an installation method.
To Choose Your Installation Method
3. Plan and allocate disk and swap space.
Determining Disk and Swap Space
4. Gather necessary system information.
Pre-Installation Checklist
5. Perform the installation.
To Install the Jetson Software
42
Lists When to Use
When you have a list of two or more items in which any item consists of two or more words Awkward Notify us if the system is making any of these noises: grinding, rattling, whirring, high-pitched whine, or out-of-tune whistling. Better Notify us if the system is making any of these noises: Grinding Rattling Whirring High-pitched whine Out-of-tune whistling 43
Lists Guidelines Use bulleted lists if the order of the items is not important. Use numbered lists if the order of the items is important.
44
Lists Guidelines (cont'd.)
Put summary or keyword information that distinguishes list items from each other toward the beginning of the item Awkward
Software undergoes alpha testing as a first step in getting
user feedback. Alpha is Latin for doesn't work.
Software undergoes beta testing shortly before it's released.
Beta is Latin for still doesn't work. Better
Alpha Software undergoes alpha testing as a first step in
getting user feedback. Alpha is Latin for doesn't work.
Beta Software undergoes beta testing shortly before it's
released. Beta is Latin for still doesn't work. 45
Lists Guidelines (cont'd.)
The syntax of the items in a list should be parallel and agree with the syntax of the introduction. Awkward Use Mail Tool to perform the following tasks: Composing a new message Forward a message to another person Better Use Mail Tool to perform the following tasks: Composing a new message Forwarding a message to another person 46
Tables When to Use
For a series of elements that have multiple properties To organize information that is best presented in a row-and-column format
47
Tables Troubleshooting If all of the entries in a given row or column are the same, evaluate whether the information can instead be described in surrounding text See whether you can logically divide long tables into separate, smaller tables Consider combining a series of small tables that are similarly organized Check whether a two-column table could be presented as a list 48
Table Example The additional parts listed in the following table are necessary to continue with the installation. Part Number Qty GM-96-3026 CB-13-2395 CG-63-6376 IB-89-3335 DE-44-8846 AS-87-2319
1 1 1 5 1 1
Name Goat, male Candle, black Chalk dust container Incense sticks Dagger, ebon, curved Altar, silver
Once the additional parts arrive, you can continue the installation on the next Friday the 13th at midnight.
49
FAQs When to Use
When you see the same questions repeatedly asked by email or encountered by your help desk To cover questions that you have not yet had a chance to include in your formal documentation To gather the most common troubleshooting questions in one place
50
FAQs Guidelines Include questions that users actually ask rather than what you want to say Be concise Link to more detailed information elsewhere but duplicate short solutions Organize long FAQs into categories and provide a Table of Contents Provide links for feedback and for further contact information 51
FAQ Example Dave Barry's Ask Mr Language Person: Q. Please review the basic purpose of the apostrophe. A. The apostrophe is used primarily as a punctuation mark in certain Lesley Gore songs, such as Judy's Turn to Cry, where the apostrophe and the s indicate that Judy is possessive, which is why she tried to steal Lesley Gore's boyfriend, Johnny, away. Q. Please explain the expression: This does not bode well. A. It means that something is not boding the way it should. It could be boding better. Q. What is the difference between criteria and criterion'? A. These often-confused words belong to a family that grammarians call metronomes, meaning words that have the same beginning but lay eggs underwater. 52
Illustrations When to Use
Include illustrations that will help the reader understand an instruction better than a text description Provide screen captures for step or task completion verification
53
Illustrations When Not to Use
Do not use a screen capture to substitute for tables or lists Avoid using screen captures in the following instances:
When forms and dialog boxes are designed
consistently across the GUI When GUI forms are self-explanatory and require no further explanation When data entry fields are labeled clearly and consistently
for the Products You Use Instead of cursing at your external product documentation, take the steps described in this section to help improve it
57
Complain File bugs Use the feedback button at the online documentation site Mention your desire for better documentation to your SE or account representative Read the documentation accompanying beta software and provide feedback
58
Contribute Provide corrected versions of incorrect documentation Sign up to document portions of open source projects Write articles with tips and tricks for open source projects or product blogs
59
Contribute (cont'd.) Offer to work with the documentation team in the area where the documentation is weak
60
Resources and References
Some sources to help you
define, organize, and write your documentation
61
Resources: Books Smart Things to Know About Knowledge Management, by Tomas M. Koulopoulos and Carl Frappaolo (Capstone, 1999) The Transfer of Internal Knowledge and Best Practice by Carla ODell and C. Jackson Grayson, Jr. with Nilly Essaides (The Free Press / Simon and Schuster, 1998) Working Knowledge: How Organizations Manage What They Know by Thomas H. Davenport and Laurence Prusak (Harvard Business School Press, 1998)
62
Resources: Online Downloadable Excel IT documentation workbook consisting of worksheets for an IP scheme, staff contact data, inventory, and projects
for technical communicators worldwide http://www.techwr-l.com
64
References Brian Warshawsky, The Fifth Commandment of System Administration, [http://www.linux.com/articles/44939], posted May 23, 2005 Brian Warshawsky, The Fourth Commandment of System Administration, [http://www.linux.com/articles/44819], posted May 16, 2005 Meredith Little, Internal Documentation: Avoiding Critical Mistakes, [http://articles.techrepublic.com.com/5100-10878_111029621.html?tag=rbxccnbtr1], posted August 28, 2000 Bill Heldman, Documenting Your Network,
