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

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

Format

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 .

Extra credits

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

Questions & Answers

Application of nanotechnology in medicine
what is variations in raman spectra for nanomaterials
Jyoti Reply
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.
Damian
yes that's correct
Professor
I think
Professor
what is the stm
Brian Reply
is there industrial application of fullrenes. What is the method to prepare fullrene on large scale.?
Rafiq
industrial application...? mmm I think on the medical side as drug carrier, but you should go deeper on your research, I may be wrong
Damian
How we are making nano material?
LITNING Reply
what is a peer
LITNING Reply
What is meant by 'nano scale'?
LITNING Reply
What is STMs full form?
LITNING
scanning tunneling microscope
Sahil
how nano science is used for hydrophobicity
Santosh
Do u think that Graphene and Fullrene fiber can be used to make Air Plane body structure the lightest and strongest. Rafiq
Rafiq
what is differents between GO and RGO?
Mahi
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
Rafiq
if virus is killing to make ARTIFICIAL DNA OF GRAPHENE FOR KILLED THE VIRUS .THIS IS OUR ASSUMPTION
Anam
analytical skills graphene is prepared to kill any type viruses .
Anam
what is Nano technology ?
Bob Reply
write examples of Nano molecule?
Bob
The nanotechnology is as new science, to scale nanometric
brayan
nanotechnology is the study, desing, synthesis, manipulation and application of materials and functional systems through control of matter at nanoscale
Damian
Is there any normative that regulates the use of silver nanoparticles?
Damian Reply
what king of growth are you checking .?
Renato
What fields keep nano created devices from performing or assimulating ? Magnetic fields ? Are do they assimilate ?
Stoney Reply
why we need to study biomolecules, molecular biology in nanotechnology?
Adin Reply
?
Kyle
yes I'm doing my masters in nanotechnology, we are being studying all these domains as well..
Adin
why?
Adin
what school?
Kyle
biomolecules are e building blocks of every organics and inorganic materials.
Joe
anyone know any internet site where one can find nanotechnology papers?
Damian Reply
research.net
kanaga
sciencedirect big data base
Ernesto
Introduction about quantum dots in nanotechnology
Praveena Reply
hi
Loga
what does nano mean?
Anassong Reply
nano basically means 10^(-9). nanometer is a unit to measure length.
Bharti
how did you get the value of 2000N.What calculations are needed to arrive at it
Smarajit Reply
Privacy Information Security Software Version 1.1a
Good
Got questions? Join the online conversation and get instant answers!
Jobilize.com Reply

Get the best Algebra and trigonometry course in your pocket!





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?

Ask