Creating a Useful Deployment Document

After working on a number of projects over the course of my career I’ve learned to appreciate the importance of a good deployment process.   As we all know at the heart of any good process is a good document.  In this post I want to share some of the basic attributes of an effective document that I have been using on a recent engagement.

For this post I am going to focus on the 3 main sections in the document, they are:

1.) Active Items
2.) Promotion Log
3.) Production Release Plan

It’s also important to note that we don’t just create this document before a production deployment.  Rather the document is updated as items are promoted through testing environments and when the updates are approved and scheduled for release.   

Active Items

When a development task gets to the point of being ready to be deployed to a dedicated testing environment it is time to add that item to the Active Items section.

For each item we capture the following attributes of the development work:

- Description: keep it short.  There is no need to write a novel here so keep it high level
- Deployable Artifacts: these are your .war, .ear, .jar…etc files
- Associated Tracking Tickets: on this project IBM Rational Team Concert is used to track our development activity (click the link for more info on this product) 
- Deployment Steps: keep this simple enough that anyone on the team can following and successfully deploy
- Sign off Person:  when everything works as expected this will be the person who will give you the thumbs up to deploy to production


Promotion Log (Ready for Deployment)

When an “Active Item” as described above has been tested and you’ve received that thumbs up for deployment, then it time to let the world know that this item is ready to go into production.

What we do is cut and paste the work item from the Active Items section into the Promotion Log.  We add in the sign-off date and we are done updating this section.
      

Production Release Plan

When we have an approved window for deployment it’s time to check the Promotion Log section and update this section with any items that are approved and ready for deployment.  This is what will be used as the deployment guide and lays out all the steps required for deployment.  For each step here it must be clear who is responsible for the work and in what order the steps will be performed.

This section breaks down further into 3 sections:

1.) Deployment Preparation – this is where all the artifacts are consolidated
2.) Server Updates - see "Deployment Steps" in the Active items section
3.) Testing – we also use this section to describe any roll back steps in the event something isn’t working as expected.

Once the deployment is completed a versioned copy of this document is stored for future reference.   The living version of the document is updated to remove any of the items deployed.

Thanks for reading!  Hopefully you are able to take something away from this and if you have any questions please feel free to contact me via email.