Even experienced managers of IT operations can stumble over the most critical part- the documentation. If only there were useful examples around! We commissioned Hugo Shebbeare to explain what is required of such documentation, and why. He has also provided the templates to make it all easy for the pen-chewing DBA or SysAdmin.

When you are managing a deployment, you will avoid a lot of problems by documenting it clearly, and in a standard format. This document must meet several obvious requirements, but, above all, should also say who is making  the change request, and give the significant dates such as testing, estimated rollout and go-live. A deployment  by itself is best seen as a mini-project, because there is a definite start and end date, a deadline, and the goals and reasons for the alteration are to be satisfied by the end of the mandatory action in production. The latter is similar to completing the statement of work, in Project Management lingo.

The sections of the document

The title of the deployment and the reference Number

The Title of the Deployment should be unique, clear and distinctive as possible.  I would recommend a limit of 60-80 characters. Generally it will echo the name of the original change request. There will be a reference number for the change request that will be used frequently by those people who eventually execute the scripts, and this has to be displayed prominently in the deployment document somewhere.

To prove that sufficient thought has gone into this deployment, one should state a clear reason why the work should be performed.  Make sure to indicate the elements that make this change easier to differentiate from change-requests if its’ name is not distinctive enough explicitly.

The Communication Plan

Don’t overlook the Communication Plan: You cannot expect people to read your mind about the changes that you need to make.  Therefore, try to think about their point of view as users, since back-end System Administrators occasionally forget to consider this community, whether a single department or entire organisation, if this is not thoroughly covered in a ‘change impact analysis’ at the inception.  Think firstly about an overview, a bigger picture, about selling this change to those who are given the right to approve/deny it outright. As everyone is inclined towards self-interest, you should take their interests into consideration also. If you have to complete a series of changes, take the incremental approach. This will involve a Master Change Request, split up into groups of system changes in much the same way as the work breakdown structure of a project, but with the individual groups of tasks placed in Deployments.  Typically, senior Project Managers will tell you to establish Pilot projects to weed out issues via feedback, and this a decent fail-safe method for implementations that have an elevated impact.   For the one who is preparing the communication with the users, it is best to indicate to them your level of experience with this type of change, therefore establishing a higher level of confidence that one’s objectives are easily attainable. In this way, it is not hard to understand why complex system changes should be handled by the most experienced of individuals.

Manpower and resources

Who is involved in the change? What is it costing, and why? (relate the resources to the tasks) You should  indicate to the users those dates that are targeted for rollout of the deployment(s).  This is where you should indicate your experience with this type of change to re-assure the users.

Security issues

Security concerns? Are they addressed? What is the potential threat? Please make sure to never forget security aspects and to ask oneself these former questions, as one of the unskippable steps to accomplishment of the respective change.

Risk Management Concerns

The risks of doing the change must be clearly pointed out, as well as the  risks associated with NOT doing the change: A common reason that such an application evolution could be as basic as to not lose confidence in the particular application vis à vis the users who depend upon it. The loss in confidence in an application or infrastructure is usually related to a lack of resources allocated to it. Examples include poor performance due to the famous Disk Vs Bandwidth Vs CPU Vs Active Memory, human resources removed from administration or maintenance of the systems, and last but not least Code Smells.

Why Does This Change Need to Happen?

Obviously, if the change is so urgent as to be required to prevent an emergency, or to rescue a  system that has become, or is about to become, inoperable, then you will not have to describe the problem in great detail. If those who are approving/denying the change request are pushing for the quick fix, then make sure that you have their explicit approval to move forward with necessary modifications to bring the system(s) back to normal operational excellence – proceeded by a complete documentation of what work was performed.  The post-mortem documentation and change request, in this case, will require a little more communication to deter the typical ‘hey, he didn’t follow the procedure’ attack from the naysayers within your particular organisation, so be prepared to preach the benefits of what you or your  team have performed repetitively to several levels of the hierarchy or stakeholders. Positive propaganda is necessary to counter the usual negativity associated with transformation.  An example regarding sensitive information could mean masking or encrypting of Payroll data in the Human Resources database, therefore one should treat the change as necessary to avoid the multiple negative consequences of unencrypted salary information from dissemination throughtout the workplace by the inevitable jealousy amongst employees.

The nature of the deployment

In documenting the deployment of the change, you must spell out clearly whether it is related to hardware, software, infrastructure, a fix/patch/bug or simply an incremental enhancement. Moreover, by categorising the variation in system settings, you will make it much easier for those who are involved in the approval process to understand.

The Roll-Back / How to Get the Systems to a Stable State

Often forgotten in the plan is the quickest method to step back from a pending change. In the worst circumstance, the change could be affecting current production; if you haven’t prepared  a clearly-documented back-out plan, there could be huge financial consequences.  With the quality of backup and source code archive tools available nowadays, there is really no excuse, nor reason to act as if the documented changes have a point of no return during deployment.

Creating a resource for the documentation of Change Management

As my ITIL and Change Management Analyst colleague Diana Foliaco has noticed, there is a distinct lack of documentation available on the web on this subject; therefore we hope to rectify that with this article, as well as providing templates if your organisation does not have a change management system in place.

Change / Risk Management Templates

The full version of the COBIT-style document is here: http://intellabase.com/DeploymentManagement.docx

Short version: http://intellabase.com/DEPLOYMENT_Document.docx

Admittedly, the first document is quite long, thus the quick and dirty short version, because one colleague at the time joked to me that the former resembled a NASA level type of documentation, but for publically regulated environments the full template is completely necessary for compliance.  Please note, that if you are in a migration involving SQL Server, I have a pretty decent Microsoft Project Template here.

Conclusions

Please do not take this as to be the only way to manage change in your organisation. Obviously, if you may already have a system such as Remedy in place for structural alterations – tant mieux.  Admittedly, I have skipped some of these steps in the past to my own chagrin.

If all that comes out of this work is that fewer people push-aside the documentation of these deployment procedures, then I am pleased.  There has certainly been plenty of interest in what has, up to now, been a neglected part of the management of change in IT. So far on the SQL Server Central blog, this subject has attracted almost ten thousand viewers, and I wish I knew exactly for my backup blog on the DatabaseHive.com ; but if Google Page Rank means anything, it is higher up on the list than SSC, that is for sure.