Nobody likes SharePoint farm documentation. I'll take that back, everyone loves documentation when they need to read it, no one likes to write documentation. This especially seems to be woven into the DNA of technical folks, or at least all the ones I’ve worked with, myself included.If documentation is so universally loved when it’s needed, why is it so tough to get people excited about writing it?
You would think the chance of being hailed as a hero when someone needed that documentation, the chance to be a superstar, would be motivation enough. But it turns out, it’s not. Working primarily in the SharePoint and Office 365 space, that’s where I see the gaps the most. In this blog post I’m going to cover why SharePoint farm documentation is so important and tell you how it’s even easier to make than you think it is.
Documenting SharePoint farms seems to be one of those things that if it’s ever done, it’s done right after installation and then never updated again, almost as if it were carved into stone tablets. Documenting a SharePoint farm install is a great idea and reaps all kinds of rewards. It makes a great punch list in case there are problems and in the unlikely event of a disaster, good SharePoint installation documentation can be the difference between a revenue generating event and being carried around on the shoulders of your coworkers and celebrated as a hero. But documenting your installation isn’t enough, that SharePoint farm documentation should be a living document that gets updated regularly.
The Irreplaceable Value of SharePoint Farm Documentation
Constantly updating documentation is a lot of work and takes a lot of time. Today’s SharePoint admin has a lot of things competing for their time and attention. It’s almost a full-time job just keeping up with how quickly the technology changes. Then there’s user support, keeping the farm running, and watching the occasional cat video on YouTube. These are busy times. Where does the added burden of documentation fit in? And what’s the ROI on it?
SharePoint Documentation for Disaster Recovery
There’s the aforementioned value of detailed SharePoint documentation during a disaster. Installation documentation is great, but updated farm information is even better. It would have patch levels, any service applications that have been added or reconfigured, new servers, and any other post installation configuration that inevitably happens as a SharePoint farm ages and matures.
Documentation has other significant returns as well that often get forgotten or overlooked in the hectic schedules that SharePoint admins have. My favorite use for good documentation is justifying funding. The days of unlimited funding for SharePoint are gone, if they were ever a reality in your company. I’ve seen documentation that showed growth trends in SharePoint used to justify funding for additional hardware and even additional headcount. Being able to quickly and easily show how much SharePoint use is growing month over month or year over year is a great way to justify additional servers or additional support staff.
Thorough Farm Documentation to Audit Changes
If additional money isn’t enough motivation, documentation is a great way to uncover any creepy-crawlies in your farm. There are usually many cooks in the SharePoint kitchen, and you can never be sure when someone throws in a new ingredient or two. It might be a patch or a 3rd party solution of some kind that solved an important user issue. Change control is great, but when things get hectic it can get overlooked. Maintaining farm documentation is a good way to keep tabs on those things and catch them early. When you bring any new members onto your team or employ outside help (with all that funding your documentation got you) they can use this documentation to quickly get an idea about what’s waiting for them.
Upgrades and SharePoint Migration
Maybe the best use of up to date documentation is when upgrade and migration time comes. Migrations and upgrades are always fraught with unexpected issues. Documentation can help ease that burden. It can help budget time and tasks, and it makes it easier to triage what content gets migrated when. Your continuously updated documentation will let you know when site collections get large and when content databases should be split up. This allows you to start migrating sooner and not having to do quite so much cleanup right before you migrate your SharePoint content. Knowing how your content is laid out, who owns it, and what SharePoint functionality they’re using will jump-start your planning and execution.
How to do a Proper SharePoint Farm Documentation?
As a seasoned SharePoint Admin though, I don’t need to tell you the benefits of good, up to date documentation. You know what it is. You feel its value every time it’s not there. If it’s so important, why aren’t we better about it? Pain points, lots and lots of pain points, that’s why. First, we need to figure out exactly what we want documented. Is it content? Information architecture? Software configuration? Hardware configuration? All of the above? Getting your arms wrapped around what to document is tough.
Who is the SharePoint Farm Documentation For?
It gets even more overwhelming when the documentation is going to have a diverse audience. Are you writing it for technical people to help rebuild the farm? Are you building it for management types to justify expenses? Both? Different audiences want different information and in different formats.
Tech folks generally want raw data. What values go in what spots, screenshots, directions that are easy to follow when the heat is on. Management types on the other hand prefer pictures and data distilled down to exactly the information they care about. After we figure out what data we collect for our documentation, we need to know how deep into the weeds we go with that content. Do we list the number of site collections or do we list each and every one of them out? Do we document how much content there is in total or do we break it out by document type? How do you create documentation that is all things to all people? That’s the main stumbling block to getting a documentation project off the ground.
How to Do the SharePoint Farm Documentation?
The biggest pain point of all might just be how to do the documentation? Even if you’re on-board with documentation being an important part of your environment and you’ve defined what exactly will be documented, getting the documentation and keeping it up to date is a challenge. It can be done manually. Someone, probably a hapless college intern, could be tasked with logging into SharePoint once a month and collect the necessary information. This of course is very error prone and likely to be forgotten after a month or two. That’s not a good option.
There’s always PowerShell, which is a great tool for automating time-consuming tasks like documenting changes, and SharePoint’s PowerShell can really get in and dig out the details. You have complete control over what information you document, with the bevy of “get” cmdlets in the SharePoint snap-in. Microsoft has even provided us a template script for documenting our SharePoint farm within an inch of its life with PowerShell. That script gets everything.
However, this approach lacks in two important areas, trending and presentation. While PowerShell can get you all the information it takes some work to get the information in a format where you can compare it month over month or year over year to see what your trends are. And once you have all the information about your farm, whether it’s an individual snapshot, or showing trends, making it look good and make sense are tough in PowerShell. It’s not going to be easy for non-technical people to create or consume without a lot of work.
So what’s the solution? Is there hope for us SharePoint Admins to get the documentation we need in a way that’s easy to generate and even easier to consume? There is. SPDocKit.
SPDocKit - The Ultimate Tool for SharePoint Documentation
SPDocKit is a whole lot more than a documentation tool, but let’s cover how well it addresses your documentation needs. While it can be run manually, SPDocKit can be scheduled to run periodically, removing the risk that you or the college intern will forget to run it weekly, monthly, or whatever interval you choose.
SPDocKit saves the results of its crawls in SQL, so all of your historical data is right at your fingertips whenever you want it. Since all the data is saved in SQL, your report choices are incredibly flexible. You tell SPDocKit what kind of report you want and it goes in SQL to get the data it needs for your report. This means one tool can create the deep technical report your IT team wants and also the pretty graphs and tables that management wants. You can also apply templates to the SPDocKit reports so that they match your company’s styling and branding. Functional and easy on the eyes. SPDocKit is the total package.
Having good documentation for our SharePoint farms eludes even the most well-intentioned SharePoint Admin. There are a lot of roadblocks and potholes between us and the documentation nirvana we seek. Fortunately, SPDocKit has our backs. It allows us to easily and quickly generate professional looking documentation without breaking a sweat.