<< Chapter < Page Chapter >> Page >
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.


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


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.


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 ( and
  • 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.


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 .

Extra credits

Some of the materials in this guide have been adapted from content on StackOverflow.com and ServerFault.com .

Questions & Answers

are nano particles real
Missy Reply
Hello, if I study Physics teacher in bachelor, can I study Nanotechnology in master?
Lale Reply
no can't
where we get a research paper on Nano chemistry....?
Maira Reply
nanopartical of organic/inorganic / physical chemistry , pdf / thesis / review
what are the products of Nano chemistry?
Maira Reply
There are lots of products of nano chemistry... Like nano coatings.....carbon fiber.. And lots of others..
Even nanotechnology is pretty much all about chemistry... Its the chemistry on quantum or atomic level
no nanotechnology is also a part of physics and maths it requires angle formulas and some pressure regarding concepts
Preparation and Applications of Nanomaterial for Drug Delivery
Hafiz Reply
Application of nanotechnology in medicine
has a lot of application modern world
what is variations in raman spectra for nanomaterials
Jyoti Reply
ya I also want to know the raman spectra
I only see partial conversation and what's the question here!
Crow Reply
what about nanotechnology for water purification
RAW Reply
please someone correct me if I'm wrong but I think one can use nanoparticles, specially silver nanoparticles for water treatment.
yes that's correct
I think
Nasa has use it in the 60's, copper as water purification in the moon travel.
nanocopper obvius
what is the stm
Brian Reply
is there industrial application of fullrenes. What is the method to prepare fullrene on large scale.?
industrial application...? mmm I think on the medical side as drug carrier, but you should go deeper on your research, I may be wrong
How we are making nano material?
what is a peer
What is meant by 'nano scale'?
What is STMs full form?
scanning tunneling microscope
how nano science is used for hydrophobicity
Do u think that Graphene and Fullrene fiber can be used to make Air Plane body structure the lightest and strongest. Rafiq
what is differents between GO and RGO?
what is simplest way to understand the applications of nano robots used to detect the cancer affected cell of human body.? How this robot is carried to required site of body cell.? what will be the carrier material and how can be detected that correct delivery of drug is done Rafiq
analytical skills graphene is prepared to kill any type viruses .
Any one who tell me about Preparation and application of Nanomaterial for drug Delivery
what is Nano technology ?
Bob Reply
write examples of Nano molecule?
The nanotechnology is as new science, to scale nanometric
nanotechnology is the study, desing, synthesis, manipulation and application of materials and functional systems through control of matter at nanoscale
Is there any normative that regulates the use of silver nanoparticles?
Damian Reply
what king of growth are you checking .?
Got questions? Join the online conversation and get instant answers!
Jobilize.com Reply

Get Jobilize Job Search Mobile App in your pocket Now!

Get it on Google Play Download on the App Store Now

Source:  OpenStax, Debugging and supporting software systems. OpenStax CNX. Aug 29, 2011 Download for free at http://cnx.org/content/col11350/1.2
Google Play and the Google Play logo are trademarks of Google Inc.

Notification Switch

Would you like to follow the 'Debugging and supporting software systems' conversation and receive update notifications?