Runbooks or How to Make Documentation As Painful As Possible

ODNS_writeaRunbook

Intro

I’ve begun the process of creating a Runbook from scratch to document a XenDesktop/XenApp environment that is completely new to me. Runbooks are useful…right? I certainly hope so, as I’m committing a lot of time to creating an exhaustive document. Having all your infrastructure and operations detailed in one place is probably best for knowledge transfer or training.  Unfortunately, it’s also great for outsourcing.

/rant on
In my prior job, the company decided that it did not want to be in the “IT business” anymore. So, as many companies are doing these days they fired “let go” the IT staff and brought in a third-party to manage operations, infrastructure, development, what have you. When this morale-destroying decision was made, my staff were directed (by me) to work with the outsourcing company to regurgitate all their accumulated knowledge. If you’ve been spared this exercise, you are fortunate. What follows is depressing and frustrating. Imparting detailed technical knowledge is difficult, especially when you’re having to document operations and infrastructure that were never documented before. Combine that with the fact that you are obsolescing yourself during this process, and you’ve got to wonder why you should come to work at all.

After many, many meetings, all this information was put into runbooks. When I reviewed them, everything was very high-level and only did a good job of describing our environment. Very little was detailed on the operations side. If you have knowledgeable staff and workers who are familiar with your technology, then I suppose this is sufficient.
/rant off

In my case, I don’t have an operations group to rely on. So, I want to document not only infrastructure in detail, but also operations. This will assist in training, but I also want to use this Runbook to improve this environment with automation. None exists at this stage and it is a barrier to scaling out the environment to support more users. So where do we start?

Define Infrastructure

First, take a 30,000 foot view of your environment. What are the major components? You’ve got a network, server infrastructure and possibly storage. Maybe start with an outline view

  1. Network
  2. Hypervisor
  3. Storage

This can be further refined (for example):

  1. Access Layer
  2. Servers
    1. Infrastructure
    2. XenApp
    3. XenDesktop
  3. Applications
  4. Users
  5. …and so on

Yeah, outlines are nice, but how do you get started?

I’m not going to sugar-coat it, this is the toughest thing to put together especially if you don’t have anything yet. The best way to get started is to keep expanding your outline with more and more detail. You can note procedures for changes, user management, application testing and so on. I’ve previously done a blog post on documenting Citrix Policies using PowerShell and MS Word. I would also highly recommend using Carl Webster’s documentation scripts. This can fill in a lot of detail for you. Carl has the following scripts available:

  • Active Directory
  • DHCP (DHCP must from from Windows Server 2012)
  • NetScaler
  • PVS (5.6 – 7.1)
  • XenApp 5 for Windows Server 2003
  • XenApp 5 for Windows Server 2008
  • XenApp 6
  • XenApp 6.5
  • XenDesktop 4

The scripts are available here: Where to Get Copies of the Various Documentation Scripts

Carl is developing other documentation scripts (XenDesktop 5 for one), so keep checking his web site for updates.

The Long Haul

I’m still actively working on my runbook (123 pages, with attachments almost 200) and have benefited from information I had from the previous environment administrators and earlier jobs, but I have my document always open and I’m making additions and edits to it daily.

So What About You?

I hope this post has inspired you to work on a run book or at least encourage documenting more of your environment and procedures. Please leave any tips, ideas, or questions in the comments. I’d like to know what you do to document and I’d like to know if you don’t document.

Thanks,
Alain

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s