What Makes Good SharePoint Documentation?

In this post I wanted to dig into the topic of documentation, specifically as it relates to documenting your SharePoint farm and configuration.  As a consultant here at C5 Insight, I rely on, create and work with documentation all the time, and I’ve come to appreciate what I think makes good documentation.  I’m not referring to any form of training or user manuals; this is technical documentation for the IT folks.  Documents vary by exactly what’s included, how they’re written and how they’re used, but the basic premise is the same.  “I need to know some details about my SharePoint farm, servers, and its configuration.”

Why Is This Important?

Go back to your first day on the job as the SharePoint administrator at Contoso (we’ve all worked there one day or another right?).  Were you the only SharePoint admin?  How did you know what’s what?  You ask your manager, “Do we have any documentation?”  He laughs, and your heart sinks.  That means you have investigative work to do.  That’s no fun, and you have better things to do.

What if instead, your manager said “Sure here’s our documentation, enjoy.”  “Awesome thanks!” you say.  You know exactly what servers are doing what, how things are configured, what is installed and URLs for everything.  What a great feeling.  When it comes to writing documentation, it is unfortunately one of those things that you will get to tomorrow, gets pushed because this server was down, or Bob needs his password reset.  But I believe it’s important to at least have some form of documentation.  This is important because:

  1. It can prove to be very helpful when planning upgrades to the next version of SharePoint.
  2. It can be useful if you have to rebuild your farm so you can easily replicate the environment.

What’s In Good Documentation?

This can vary in topics and format.  These are the topics that I believe should be included in good SharePoint Documentation:

  • Farm Infrastructure
    • Build number (service pack + updates)
    • Server Diagram?
    • Service accounts and passwords (careful with passwords)
    • Farm passphrase
    • Farm Servers & services
      • Servers
        • Installation info (especially for SQL)
        • SQL alias
        • SharePoint Log locations
      • SMTP settings
    • Web apps
      • URL redirection
      • SSL certs
      • User Policies
    • Managed paths
    • Site collections
    • Farm app pools
    • Farm solutions / Apps
    • Service apps
      • Customization to svc apps
        • User Profile Service
        • Search
        • Managed Metadata
        • Apps (2013)
        • Distributed Cache (2013)
      • Office Web Apps?
    • Managed accounts
    • SQL databases
    • Service instances
    • Site topology
      • Diagram
      • How many subsites?  How many users, how much content, when was it created and updated, which templates used, which has associated workflows?
  • Site Configuration
    • This will vary widely based on your configuration, but consider:
      • Solutions
      • Content types / site columns
      • Libraries
      • Web Parts
      • Publishing Settings (master pages, page layouts)
      • the list goes on …

How Do You Get What You Need?

The format can be simplistic and auto-generated by tools or scripts, or be complete and well-rounded.  The most important part is having one.  You may notice that I didn’t mention governance or disaster recovery.  That’s because those should be separate documents!  There are entire books devoted to each topic, so I won’t discuss here.  So how do you get this information?  There are some tools, some PowerShell scripts, and of course always the manual look and copy.

SPDocKit

SPDocKit hasn’t been around all that long I believe, but is a well-rounded tool.  It is a good fit for consultants based on how it’s licensed.  You can find reviews for it on sharepointreviews.com.

SPDocGen

SPDocGen has been around since 2007, and was converted by the community to work with 2010.  It’s a great tool to give some good detailed tables of information in Word and XML format.  The 2007 version will also dump passwords of service accounts / application pool accounts which is nice if you happen to have misplaced it for an old environment, or if you took over for someone else.

SPSFarmReport

SPSFarmReport is a favorite by Microsoft support, when they need to quickly gather information on your environment.  Currently it only supports 2007 and 2010, it is unclear on a version for 2013.

PowerShell

The rest of the links I have compiled use PowerShell scripts in some form or fashion to create an inventory or listing of an environment.

As I said, it all depends on what you’re trying to gather, and how you need to display it.  Of course feel free to write your own script or cobble these together.  Whatever you do, make time for this, it’s important!  What if you just take site collection backups, and your single farm server completely dies.  Now what?  I’ll say it again, make time for documentation.  You just might learn something along the way.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s