Don’t hesitate to ask your R&D for software documentation!

If you, as an Operations Engineer, have experience working with third-party software, it is most likely that you enjoy a full set of documentation for used products: deployment guide, installation manual, user’s guide, release notes, upgrade procedures, troubleshooting procedure, etc. When you switch to use in-house R&D products you see that the products, in most cases, are not accompanied by any usable Operations documentation and this makes the process of deploying and running the software quite challenging and not a scalable task. This blog will help you to define some minimal documentation requirements for in-house R&D products, and this addition should not provide any significant burden for your R&D team.

In general, each new R&D product should be accompanied with the following set of documentation:

• Engineering description
• Installation guide
• User's guide

All consequent software releases should be packaged with the following documents:

• An updated version of the engineering description and user's guides; since the software is already deployed (and hopefully the procedure is scripted in a central configuration management system like Puppet) there is no real need to update the installation guide (but still nice to have!)
• Release notes (change log)
• Upgrade guide

The documents should be two-three pages long, and should be addressed to experienced software users. Normally the documents will be used as training materials for new Operations hires, and will not be used to independently learn the in-house software products from A to Z (most R&D teams will not be able to easily produce the documentation on such a high level). 

Engineering Description

An engineering description document of a product should cover the following topics:

• What is the product designed for?
• What are the primary functions of the product?
• How the application stores data?
• What are the main components of the product?
• How the product is communicating with other internal and external components?
• What are the main data flows of the product?
• What environment is the product designed to work in?

Installation Guide

An installation guide document should answer the following questions:

• What are the requirements of the product (hardware and software)?
• How to install all components of the product?
• Location of binary, configuration, data and log files
• How should the product be configured? 
• How should all related components of other systems be configured to work properly with the product?
• How to verify that the installation has been performed correctly?

User's Guide

A user's guide should normally cover at least the following topics:

• How to start and stop the application?
• What are the possible valid inputs of the application?
• What are the expected results of the application?
• How to manage the application?
• How to monitor that the application is functioning correctly?
• How to recover from application crashes and ungraceful shutdowns?
• How to read and understand the log files?
• How to backup and recover the application data?

Release Notes

A Release Notes document should highlight all significant changes in the software release. It should mention all serious bug fixes, engineering changes, data store modifications, etc.

Upgrade Guide

An upgrade guide should answer the following questions:

• How to prepare the application for an upgrade process?
• How to modify the configuration files (if required)?
• How to migrate the data store (if required)?
• How to install/upgrade the software components?
• How to validate that the upgrade has been performed successfully?
• How to perform a rollback procedure?

Upgrade guides are normally used by Operations to prepare internal procedures for upgrading of pre-production and production environments with the new software versions.

Obviously, the mentioned questions do not cover all possible aspects of a software product, and are aimed to define some minimal set of product information which is enough for Operations to use the documentation in its day-to-day activity and new hires training.

A corporate Wiki server is probably the best place to manage the R&D documentation.

If you can think about additional topics which should be included in the minimal documentation set, please feel free to leave a comment for the post!