What makes a professional deployment guide in SharePoint?
Deployment Guide is always required naturally in software development project. However, writing a good deployment guide is not easy. I have seen a lot of deployment guide without care, contributing to bad deployment of an application. In SharePoint, it becomes more complicated to deploy an application if your deployment guide is written without care. In real-world scenario when SharePoint farm hosts many applications developed by number of different development teams or vendors, deployment task is usually done by the internal staff team who may have just a little bit of SharePoint knowledge.
This article is going to cover what should be written in a professional deployment guide in SharePoint. As a SharePoint consultant, you should be aware of writing to satisfy your customer by your professional service offering.
Note that the deployment mentioned in this article is not only to run a PowerShell script to deploy a WSP package solution, but also to configure SharePoint service application, or sometime configure regional setting.
What would be a professional deployment guide?
To me, a professional deployment guide firstly should explicitly describe step by step to simplify the deployment step. Writing in a special format like a book is useless because the one who deploy the SharePoint application needs to slowly deploy and track what have been done.
Next, a professional deployment guide targets to a SharePoint beginner to help him successfully deploy the application without any error. Because you can’t measure experience level of the one who deploy the application, the best way is to make assumption that an absolute SharePoint beginner can successfully configure and deploy your application.
Next, pre-requisites listed in the deployment guide before the deployment should be changeable with no deployment impact. For example, if IE 9 is required at least for the deployment, the change of browser version should not make impact on your next deployment.
With your deployment guide, the one who deploy your application should not have to start from the first page. This basically means if he has performed the first 3 steps and left the computer for 3 hours, when he is back he should be able to continue the deployment at step #4.
Finally, to me personally a professional deployment guide in which next deployment does not require a change. If it requires, then every time of the deployment, you have to update the guide, and far future the change management will be hardly controlled.
Recommended structure for a SharePoint Deployment Guide
By my experience having involved in over 60 SharePoint implementation projects so far, I realize that if the deployment guide is not written well then the deployment is far from the deadline and customers may be upset waiting for you, even you are the one responsible for the deployment. Below is the recommended structure of a good deployment guide and I will explain more on each section.
It’s to me very important and must be documented in your deployment guide. Imagine your deployment is a workflow. Draw it to see how the dependencies look like. This is to avoid deployment failure if missing dependency. Look at an example below:
Obviously before creating user property, user profile service must be upgraded. So the script to create user property must verify the user profile service connection. Similarly, if you still haven’t upgraded user profile service application, you can’t create a corresponding MySite whose properties are stored in the upgraded user profile server application.
Without the deployment flow, troubleshooting during the deployment is completely difficult, and sometimes you have to start from the first step.
This section provides specific requirements before your applications deployed into SharePoint production farm. There should be at least the following topics to be covered in the pre-requisites section in your deployment guide:
- System: Describe specific system information that your application is deployed to, including Windows service if required.
- Browser: Describe browsers your application is compatible with.
- Account: Describe all accounts with specific permission needed during your deployment
- Package: Indicate what are included in your package including the location
In System section, provide system requirement before the application deployment is performed, including the following:
- Windows Server, SQL Server and SharePoint version in the target environment.
- Physical topology of the target environment
- Special patches/security updates/hotfixes if required
- Security requirement or hardening before the deployment
In Browser section, provide browser version which is compatible with your application, during the deployment. The reason is that if your application is fully customized and doesn’t require ActiveX, non-IE can be used. However, if ActiveX is required so the required browser must be 32-bit of Internet Explorer. Sometimes your deployment guide troubles due to wrong indicated browser.
In Account section, describe all accounts with specific permission needed during your deployment. For example, below:
In Package section, you must indicate the location where your deployment folders or scripts are. This is very important to be manageable. You must also describe what each script does in the deployment folder even if the folder has just a few of files. See the following sample below:
This sounds easy to be written doesn’t it? No it does. Having provided consultancy to number of different customers, I realize the following rules are inevitable:
- For every big step, there must be steps for Login to where, use which account, especially for a large SharePoint farm which is designed into multi-tier model.
- Format with bullet points to help readers easily understand and follow.
- Don’t copy the entirely source code (line by line) into the document because this shall not work if the ready use Ctrl C & V. Ironically this happens almost time. Instead, indicate PowerShell script and T-SQL script to automate configuration and deployment.
- Indicate explicitly if your value/parameter is constant (e.g. web application name, site collection name)
- Insert screen to the Deployment Guide for preview. If your step is hard to understand, screen is very useful.
Sometimes your deployment is successful as stated Central Administration. It’s true in a simple deployment in which you just need to execute a PowerShell script to install and deploy a WSP package solution without any special configuration. However, in enterprise solution, there are number of different components (for example an application retrieving user profile stored in User Profile Service Application, before executing code logic to do something).
Deployment validation is crucial to your deployment guide. This provides a check-list to validate if the deployment is successfully expected. The met expectation means the creation of SharePoint components (custom list, custom timer job, user group, feature…) is complete.
The list of common issues is like a knowledge asset that is very helpful. Issues are accumulated every time you encounter issues during your deployment. Hence, if your deployment guide covers it, that’s perfectly perfect.
If custom timer job is not present on the Job Definition page, check Central Administration service and SharePoint Foundation Web Application service. These services must be started on the same machine.
A professional deployment guide is to help everyone, especially internal team at customer successfully deploy an application that fully meets the expectation, without troubling in terms of testing. It’s also to strengthen business trust in your customer.