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

what does nano mean?
Anassong Reply
nano basically means 10^(-9). nanometer is a unit to measure length.
Bharti
do you think it's worthwhile in the long term to study the effects and possibilities of nanotechnology on viral treatment?
Damian Reply
absolutely yes
Daniel
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
characteristics of micro business
Abigail
for teaching engĺish at school how nano technology help us
Anassong
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.
fullerene is a bucky ball aka Carbon 60 molecule. It was name by the architect Fuller. He design the geodesic dome. it resembles a soccer ball.
Tarell
what is the actual application of fullerenes nowadays?
Damian
That is a great question Damian. best way to answer that question is to Google it. there are hundreds of applications for buck minister fullerenes, from medical to aerospace. you can also find plenty of research papers that will give you great detail on the potential applications of fullerenes.
Tarell
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
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