Quick notes on handing over knowledge

I recently got asked if I have any examples of things to hand over to a production support team when doing an agile project.

I guess, in fact, it doesn’t matter if you are handing over to someone else or supporting something yourself when you go live.  Either way you want something to refer back to.

List of things that the support team needs to respond to

So, my first step is to review my testing to see if any of the following should be documented:

• Known errors and workarounds
• Things that typically go wrong … or seem to go wrong.  These are things that are currently working, but that the testers think will come up in production.
• Frequent questions people ask.
• What the error codes mean when they come up – and where to look for a solution

I like to document these using something called KCS or “Knowledge Centered Support”.  This is an out of the box knowledge management structure for a support team.  You can create levels of knowledge, owners or knowledge and other cool things.  But for our purposes I would start with knowledge articles.

A typical knowledge article does not show “known defect – system looks sad.”  Instead it lists the known issues or typical questions that come up.  You can find some different formats or templates if you google “KCS article template.”

I find this format great as you can translate one story, work around or defect into one article.

Basic roles and starting points

I like to list the system owner, the team contact details and the different help desks that assist with different things. For example if you are helping a user and need the infrastructure team – it is easier to have it in front of you.

Licences to keep and how to load and monitor the system

I once had a software licence expire while I was a production support manager and nobody seemed to know where to go to get it fixed.  So now I like to keep the following handy

• How to run a backup and restore
• The storage details for the latest source code
• The instructions for loading patches and updates
• The release and roll-back steps
• The API and service codes and how to version control them
• Any licences that need renewing or that need evidence of prior payment etc

Alongside this, I also want to know:

• The automated monitoring and log file processes that should be running
• The manual monitoring and how to predict when the system will slow down or start misbehaving
• Any temporary systems or tactical solutions (For example if you are running two systems in parallel and doing some manual reporting)
• A list of services that are typically up (what happens when they are down? How can you restart them? How and when should you kill them?)
• A good holiday resort and the location of fake ID’s if we can’t support the system

Architecture, regression testing and system analytics

A lot of systems have regression testing in place, often even automated. If this is the case then I would like to store what I have in a format that allows it to be maintained and extended.

Also – a lot of systems have customer analytic stuff in place – so it would be ideal to have a guide to what it means and how to update it.

All systems have an architecture. For some of these that architecture is self-evident because it is either well documented in the system itself or it follows standards.  In other cases I want to know:

• System stacks and things like blacklists (don’t use blah) or other rules
• Coding and design standards
• Business rules and processes and procedures if applicable
• Other things relevant to describing the system

Flavor to taste

This all sounds like a lot and it is. But it is surprising how much the team know when they look after even a simple system.  In some cases you can leave it in people’s heads and in (many) other cases it is worth putting it all together.

I like to have a searchable set of accurate scratch files rather than a beautiful manual that is hard to access and use.  So start with the basics and evolve it as you go.  This can be done best in testing, since you can test the material as you build it … but I have done it for systems I have inherited from mysterious hermits who told us nothing about what we were in for.