How to Write a Version Description Document or Release Notes

Scope

This document describes the requirements for creating a Version Description Document (VDD).  Specific projects at MicroTools can tailor these requirements on a project by project basis with the approval of the Director of Engineering or the Director of Marketing.

Purpose

The VDD is the vehicle used for defining a specific release of software and the means of configuration control to track and control versions of software being released to production or to a contracted customer.  A VDD is required for every piece of software that is either released to manufacturing or sent to a contracted customer.  Every proposal for software should include allocating time and money for generating a VDD with each release.

The VDD provides a description of the contents for a specific software release, the methods to re-create the software, the known problems and changes from the previous release.

 

Every proposal for software should include allocating time and money for generating a VDD with each release.

 

 VDD Production

Production of as much of the document as possible should be automated.  For example, the version information generated from the source code, the known problems generated from the bug tracking database, and the list of files from the actual source code repository.

Sample Outline

1.0             Introduction

Provide a general description of the software and the customer or product it is targeted for.

2.0             Scope

This section should identify the software and this particular release.  It should describe the applicability of the software.  In addition, there should be a point of contact for the most knowledgeable person for the given software release.

3.0             Version Description

3.1             Compatibility

This section shall include a list of systems and subsystems that this software is compatible with.  This includes both API’s, Operating System versions, Interface Control Documents, and hardware versions.

3.2             New Features

This section shall describe any of the new features added with this version.  These shall be broken down into features that changed by the requirements specification and those that changed due to design changes not stemming from a known problem.

3.3             Known Problems

This section shall describe all of the known bugs fixed in this version.  It shall provide a reference to the problem (problem id) in the bug tracking software used.

3.4             Build Procedure

This section shall describe how the release can be created from the source documents. Included in this section is the exact version of all of the tools used to create the release and where the tools can be procured.

3.5             Installation

This section shall describe the methods for installing the software both in manufacturing and for updates.

3.6             Inventory of Changes Installed

This section shall include a list of every single component that has changed since the last release including some of the same content provided in the Inventory of Software Contents.

 

3.7             Inventory of Materials Release

This section shall include the various formats that release may take and where each is located.  For example, there may be a release to production for new hardware, a patch for existing customers, and an archive format. Each different format shall be described.

3.8             Inventory of Software Contents

This section shall include a list of every single component that goes into the software including the date, time and size of each component as well as where the repository for these components is located.  If a version control system is used, it must retain the date, time and size of each component.

 

This is an example of what a quote request form could look like.