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

how to know photocatalytic properties of tio2 nanoparticles...what to do now
Akash Reply
it is a goid question and i want to know the answer as well
Maciej
Do somebody tell me a best nano engineering book for beginners?
s. Reply
what is fullerene does it is used to make bukky balls
Devang Reply
are you nano engineer ?
s.
what is the Synthesis, properties,and applications of carbon nano chemistry
Abhijith Reply
Mostly, they use nano carbon for electronics and for materials to be strengthened.
Virgil
is Bucky paper clear?
CYNTHIA
so some one know about replacing silicon atom with phosphorous in semiconductors device?
s. Reply
Yeah, it is a pain to say the least. You basically have to heat the substarte up to around 1000 degrees celcius then pass phosphene gas over top of it, which is explosive and toxic by the way, under very low pressure.
Harper
Do you know which machine is used to that process?
s.
how to fabricate graphene ink ?
SUYASH Reply
for screen printed electrodes ?
SUYASH
What is lattice structure?
s. Reply
of graphene you mean?
Ebrahim
or in general
Ebrahim
in general
s.
Graphene has a hexagonal structure
tahir
On having this app for quite a bit time, Haven't realised there's a chat room in it.
Cied
what is biological synthesis of nanoparticles
Sanket Reply
what's the easiest and fastest way to the synthesize AgNP?
Damian Reply
China
Cied
types of nano material
abeetha Reply
I start with an easy one. carbon nanotubes woven into a long filament like a string
Porter
many many of nanotubes
Porter
what is the k.e before it land
Yasmin
what is the function of carbon nanotubes?
Cesar
I'm interested in nanotube
Uday
what is nanomaterials​ and their applications of sensors.
Ramkumar Reply
what is nano technology
Sravani Reply
what is system testing?
AMJAD
preparation of nanomaterial
Victor Reply
Yes, Nanotechnology has a very fast field of applications and their is always something new to do with it...
Himanshu Reply
good afternoon madam
AMJAD
what is system testing
AMJAD
what is the application of nanotechnology?
Stotaw
In this morden time nanotechnology used in many field . 1-Electronics-manufacturad IC ,RAM,MRAM,solar panel etc 2-Helth and Medical-Nanomedicine,Drug Dilivery for cancer treatment etc 3- Atomobile -MEMS, Coating on car etc. and may other field for details you can check at Google
Azam
anybody can imagine what will be happen after 100 years from now in nano tech world
Prasenjit
after 100 year this will be not nanotechnology maybe this technology name will be change . maybe aftet 100 year . we work on electron lable practically about its properties and behaviour by the different instruments
Azam
name doesn't matter , whatever it will be change... I'm taking about effect on circumstances of the microscopic world
Prasenjit
how hard could it be to apply nanotechnology against viral infections such HIV or Ebola?
Damian
silver nanoparticles could handle the job?
Damian
not now but maybe in future only AgNP maybe any other nanomaterials
Azam
Hello
Uday
I'm interested in Nanotube
Uday
this technology will not going on for the long time , so I'm thinking about femtotechnology 10^-15
Prasenjit
can nanotechnology change the direction of the face of the world
Prasenjit Reply
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
Berger describes sociologists as concerned with
Mueller Reply
Got questions? Join the online conversation and get instant answers!
QuizOver.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