SharePoint Documentation – Why Does it Stink?

I hear there’s a problem these days of people saying…. I’ve got the governance doc, so I’m now good to deploy.  I’m now going to have a successful deployment.

Have I created a monster?  In my attempts at addressing the lack of planning and of awareness around designing a SharePoint service not just installing software, I find more and more are now realizing that “Governance” is something they were missing.  More than that it really that they were missing a service definition, missing an exec sponsor, missing roles and responsibilities.  Governance has become a buzzword, and the original definition is being lost despite my attempts at defining it as designing a service offering. 

Governance uses people, process and technology to define a service [offering], mitigate conflict within an organization [and across multiple organizations]. – Craig Roth, Burton Group

(I just added the offering to add more context and the multiple organizations piece to include extranets. -Joel)

Paul Culmsee (my Governance arch nemesis and friend) uses the word “assurance,” but I find that it lacks legs.  That word lives in the support world around optimization and SLAs, but lacks the comprehensiveness required in providing the describing the service and addressing the conflicting requirements that come from the business. I can’t do anything about the fact that Governance has become a buzzword.  (By the way, you have to look at the IBIS issue based mapping on the site definition debate encapsulated into a series on one best practice to rule them all.  Incredible work Paul!)

How do you address or prevent SharePoint Chaos? How do you address or prevent SharePoint Anarchy?  You address it by creating not just a document, but start by ensuring you are creating the relevant roles responsibilities and service offering that will ultimately allow you to achieve the ultimate goal of economies of scale to govern your deployment.  If you’re overwhelmed you MUST start with the checklist.  It simplifies this whole governance thing, and takes the thousands of planning content pages into a 30 tiny page deployment essentials checklist.  Use that as a tool when writing your plans.

So what documents do you need for a deployment?  Does it stop at Governance plan?  No. That’s where it all begins.  You know you want to design something that you have a vision for, now you can start planning.

TechNet and MSDN are on a continuous publishing model, maybe you should be too!  That’s one reason SharePoint documentation stinks!  It never ends.  You must continuously update and document your changes, let alone update your plans as the scope changes.  The service offering will change, and you need to know where you’re going. 

Plan, Deploy, Operate, Optimize

• Governance Plan – Defines the service offering, roles and responsibilities, vision/mission, high level technical and business requirements.  This needs to be clear and concise and is a living document.  Much of what is in here can be broken out including service definition, service management functions, change control processes, Metrics and measures, reporting requirements, etc… I’ve now got a good filled out Collaboration Governance Plan (Required)
• Planning Guide – Next level of detail around planning, the project manager show work with operations and the business to own this document.  Appendix should include links to the deployment project plans including timelines.
• Operations and Support Guide – Operations break down of roles and responsibilities to the task level.  This also includes detail on backup restore, troubleshooting which may be broken into multiple troubleshooting guides for Tier 1, 2, 3, etc…  Disaster Recovery may be broken out into its own document.
• Maintenance Guide – While this information may be part of the Operations guide, there are some common ongoing changes around disk optimization such as DBCC, Defrag, Reorganization of databases and information architecture structural changes.  This guide helps define the ongoing maintenance and frequencies and OLAs. (Optional)
• Security Guide – This document should include from authentication, authorization, permissions, hardening, information policies, penetration plans, OLAs with security team, ISA and firewall rules, IAG settings and plans.  Any recurring review processes for service reviews and testing (hotfixes, patching, service packs).  Also should include kerberos considerations, web parts, SSO, and so on.  Document Management systems may have guidance around data retention policies that get broken off into an information policy document.  Anti virus software and policies around desktop browser and OS requirements and levels. (Required)
• Development/Customization Guide – This should take what is outlined in the Governance Plan to a much more detailed level including break down on Dev –> Test –> Production.  Development team may have their own set of documents breaking down Developers vs. Testers including SCRUM models, and documentation around the projects
• Testing Guide – Along with the Development lifecycle the roles  of the test team and their SLAs and OLAs should clearly be defined.  This may fit into a Development Guide.  Outlining the test planning requirement and tools to be used might help to provide consistency.
• Communications Guide – This should include planned and unplanned downtime notification templates including policies and SLAs to be communicated around the service.  Is there a website for communication, where are the FAQs, training brown bags, community plans, how do you contact support?  Support should be involved in this.  If the IT organization is supporting the business by building solutions and identifying needs, these should be captured in an engagement plan.
• Monitoring Guide – Uptime SLAs, performance SLAs, and monitoring software to be used.  Synthetic transactions?  SCOM?
• Others? Third Party solution guides, Consulting engagement policies and processes…  How about a roadmap guide!  or a SharePoint Guide to the Guides.

As an Ops guy I use to HATE writing documentation.  No one read it, so why write it.  Ultimately as I look through these guides, most of it is simply capturing decisions that are made, and capturing the processes, technologies, and resources outlined for the service backed by SLAs and Metrics.  Are we succeeding?  These docs would help guide us.

The operations and troubleshooting guides as well are living documents that more clearly identify the support tiers and levels.  Do you need 1000 pages to execute?  Maybe, but probably not.  You simply need to capture the decisions being made and ensure the processes are optimized as the service matures from pilot to production and beyond.

Deployment is not over at launch!  While these docs may be required in some organizations to be flushed out over the first 3 months of a pilot, these should become living documents reviewed by the respective teams that are governed by them.  Don’t forget the requirements around optimization and verification post launch.

Some people may hate me for listing these not only because now they are really going to have to do more documentation, but others will praise there being a list.  Many, many, many consultants consider this list and their own custom lists to be proprietary and part of their SharePoint Practice.  If you sign up for SDPS, you’ll find it’s about identifying what information needs to be gathered to define the SharePoint service.  That’s what these guides are really about.  If seeing this list encourages you to hire smart/experienced consultants or those with experience to help you be successful, then I’ve done my job.  Not all of these documents may need to be completely flushed out at launch, but you can see the value in having answers around these areas prior.