Skip to content Skip to navigation Skip to collection information

OpenStax_CNX

You are here: Home » Content » Debugging and Supporting Software Systems » Creating a Supportable and Maintainable System

Navigation

Recently Viewed

This feature requires Javascript to be enabled.
 

Creating a Supportable and Maintainable System

Module by: Warren Myers. E-mail the author

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

Note:

"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

Note:

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.

Collection Navigation

Content actions

Download:

Collection as:

PDF | EPUB (?)

What is an EPUB file?

EPUB is an electronic book format that can be read on a variety of mobile devices.

Downloading to a reading device

For detailed instructions on how to download this content's EPUB to your specific device, click the "(?)" link.

| More downloads ...

Module as:

PDF | EPUB (?)

What is an EPUB file?

EPUB is an electronic book format that can be read on a variety of mobile devices.

Downloading to a reading device

For detailed instructions on how to download this content's EPUB to your specific device, click the "(?)" link.

| More downloads ...

Add:

Collection to:

My Favorites (?)

'My Favorites' is a special kind of lens which you can use to bookmark modules and collections. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need an account to use 'My Favorites'.

| A lens I own (?)

Definition of a lens

Lenses

A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags? tag icon

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

| External bookmarks

Module to:

My Favorites (?)

'My Favorites' is a special kind of lens which you can use to bookmark modules and collections. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need an account to use 'My Favorites'.

| A lens I own (?)

Definition of a lens

Lenses

A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags? tag icon

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

| External bookmarks