The most important aspect of any systems project - whether an individual tool, a product release, or a site-specific implementation - is that it is supportable: the right kind of documentation, with the proper contents, can make that goal a reality.
Introduction
The most important aspect of any systems project - whether an individual tool, a product release, or a site-specific implementation - is that it is supportable: the right kind of documentation, with the proper contents, can make that goal a reality. This guide draws on years of experience of development, support, and site implementations of projects ranging from simple scripts to enterprise-managing environments.
Types of documentation
Developer-to-support
Documentation from the development team to the support team is vital. Without it, any product will succumb to unsupportability, and die.
Ideal requirements from development:
- the documentation of the code (javadoc, doxygen, etc)
- functional specification (if it exists)
- flow chart/schema of the way the application works
- what can be backed-up vs what cannot (database(s), configuration files, etc)
-
Details on the build process
- source code repository view/login information
- ticketing system information
- where to get current source
- how to
file bugs (they will happen)
- deployment diagram
- the "why" of how it works (ie design/implementation choices)
- other software used
- route to provide patches either to the source or to customers (ideally, both)
- location(s) and format(s) of log file(s)
-
User manual
- how it works
- features list
- system requirements (CPU usage, memory, disk space, etc)
- specific configurations needed
- command-line arguments/switches
- screenshots of operations and output
- user-customizable portions (eg there is a scripting component or available API)
- start-up and shut-down procedures
- primary contacts for each component, aka the "escalation path"
-
Testing/qa document
- where documentation is stored
- default application usernames/password
- details of server IP and default admin / oracle / websphere passwords
- any support SQL/tools created by the development team (for analysis, loading data, etc)
- all known issues with the current build
- "unusual" dependencies (eg if the FQDN or simple hostname is changed, the application cannot start)
- encouragement for feedback from Support as to what else they want to see
Almost equal in importance to the content of documentation is its format - the more open and accessible, the better. That may come in the form of wiki pages, html files, pure text, or PDFs. Whatever is chosen, though, needs to be easily and readily accessible to whomever needs to know - avoid proprietary formats like Microsoft Word.
"Support" may not exist for a given product as such - the "support" available may be in the form of a community of users with a mailing list or forum (such as is often the case with
open source software ). The ideal documentation listed herein still applies, but its target audience will be a little different if it's not handled by a formal support group.
Field-to-support
When products are implemented at a customer site, ideally the vendor's support team will receive a set of handover documentation to ease their lives. At one point in my career, I was involved with creating, and then maintaining/improving, the field-to-support hand-off document for the product I worked most heavily with. That document helped alleviate headaches experienced both by support getting a new customer, and future field work wherein changes were perpetrated on an existing environment via upgrades, extensions, etc.
Basic components of the field-to-support documentation
- customer name and contact information
- field representative(s) contact information
- platform(s) used in delivery (eg, Windows Server 2008 R2 for SQL Server host, RHEL 5.5 x64 for application, etc)
- hostname(s) of server(s) used in the deployment
- hardware specifications of the server(s) utilized (eg 8 2.4Ghz CPU cores, 16GB RAM, 73GB local storage, 300GB SAN storage, dual Gig-E (10.10.10.5 and 10.10.20.5))
- verification that prerequisite packages are installed (eg the out put of
rpm -qa on a Linux system)
- customer sign-off on basic functionality
- notated list of non-tested / non-functional component(s) (and why they were not tested / don't care they don't work, etc)
- customer sign-off on any site-specific configurations or customizations
- copies of all customized configuration files
- copies of all field-developed add-ons / customizations
Of course, the specific individual components of any given field-to-support hand-off documentation would be modified for a given product.
Support-to-others
Often enough, issues, bugs, and other "gotchas" are not found by developers or by the QA team - they are
found by end-users of a given tool. Documenting those items back from the field so others can benefit, or so
bugs can be resolved, is a great boon.
Most often, these common issues will be collated into a Frequently Asked Questions list (FAQ) or Knowledge Base (KB). FAQ and KB articles generally prove invaluable to many parties - other support engineers, customers, developers, management, sales, etc.
Sources for kb articles
Knowledge Base articles generally form from two primary sources - support tickets, and forums (internally or externally facing). Common issues can often be better solved by creating one good "how-to" or "workaround" article instead of having users ask the same thing over and over again (but worded differently each time). this saves support engineer time, customer time, and makes all parties involved happier.
Internal vs external kb articles
Depending on the product, there may be a wide array of information that customers "cannot know" - who wrote what, similar failures at other customers, who other customers are, etc. Likewise, some documentation available to aid in troubleshooting a problem may be in the form of saved chat transcripts, raw wiki journals, poorly-written notes, etc. It is up to the support engineer to cull both internal and external data into a form that an end-user can benefit from.
At one job I had, we had both internal and external sources: a wiki and a
Plone instance were used internally, along with
IRC ; externally we had a small-but-growing KB database. Most of us who worked in support at the time also had our own
"crib notes" of things we'd run into before that we drew on to answer new issues. All of these sources were routinely exercised to help an ailing customer with his problem
du jour .
Some of the materials in this guide have been adapted from content on
StackOverflow.com and
ServerFault.com .
