Agile documentation: Handover to production support

What knowledge does a production support team need when a project goes live? And what do project teams actually give them?

Some agile teams catapult story cards across to the support team with no thought as to whether these will be of any use to anyone.

Even worse, some teams think that being “agile” means “never having to document anything and never having to say you are sorry”.

 

It is true that many agile teams release code fortnightly, support their own systems in production and replace complex documents with code that is easy to support. Where this is the case, I think there is a significantly reduced need for hand-over documentation.

But many agile teams deploy software into an environment where their product is supported by at least one help desk and often by multiple business support and IT production support teams. And under these circumstances there is a need for substantial knowledge transfer to enable the effective support of the new or improved system.

Some people lament the good old days when waterfall projects produced far more documentation, but even then most of the documentation was designed to help the team develop the system and get it into production, rather than being designed to help people support the system once it was in production.

But it doesn’t have to be that way.

I think, for example, that the following approach is quite straight forward and will work on both agile and non-agile projects:

• Define the needs of those who are going to be around after the project;
• Come up with a strategy to give them the knowledge they need; and
• Implement the strategy during the project.

It can’t really be that simple of course, or project teams would already be doing it. So lets look at the approach in a little more detail, and hopefully I can demonstrate that it would work on your next project.

Define the knowledge needed to sustain the solution

You can capture the support needs for each support team by using any approach you want. You might, for example, use stories, Use Cases, process models or even requirement document templates.

I am assuming that you will use stories to capture their needs, so I have created an explanation of doing this if you are want to read it. I am also assuming that the stakeholder analysis is quite easy because you know who will support the system and you don’t have to do a full change readiness assessment on their ability to do so (search for “change readiness” on my blog if this part of the process is complicated on your project).

If you do not know who will supporting the system when the project is over, then this represents a substantial risk that must be identified and mitigated.

In some cases you may even need to create and implement a support model and then build the support team from scratch. In this case the story based approach I described should still work well, but there will be a lot of work involved.

Devise a knowledge transfer strategy

A knowledge transfer strategy communicates how you will provide the different support groups with the information, skills and knowledge they will need.

Since you have already identified who the support teams are and what they need, then you just need to add a few more details and you have a strategy:

1. The delivery method or channel for transferring knowledge (such as training course, hand-over document, video presentation, e-learning, weekly release meeting).
2. The person or group responsible for communicating the knowledge (eg Bill the tester, the training team, or the Ingrid the implementation).
3. When the communication will occur (eg weekly, once during UAT).
4. Any key stakeholders whose approval or support is needed.
5. The source for the knowledge to be created from (eg the user stories, scenario testing, the test team, or even a separate stream on the project).

In some projects the strategy is all you need. But in others you might go further and create a communication plan to track the different things being provided to different groups during the project. A possible plan might look like this:

Knowledge/skill	Stakeholders	Responsibility	Method/channel	Timing
Known defects	prod sppt	Joe	Known defect report	Completion of UAT
New features	Prod sppt, line managers	Beth	Showcase	Fortnightly
New features	Prod sppt	Beth	Involve prod support analyst in testing	Every iteration
New features	Prod sppt	Beth	Release notes	Completion of UAT
New procedures	Prod sppt	Beth	Convergalator 101 training course	During UAT

 

Implement the strategy

A common, and successful, approach to preparing training material, production support notes and so forth is to add an iteration to the project to do it all. This is often called the “hardening” iteration. Essentially the iteration involves scalability testing, performance testing, migration preparation and testing, any remaining bug fixing and the preparation/handover of any information needed to support the system.

But I don’t like doing this because I find it is too much knowledge to try to consolidate in too short a time.

So the three approaches I like to use are:

• Appoint a specialist trainer/technical writer and treat them like a developer (ie, while the developers are building software, the technical writer is building knowledge artefacts for handover);
• Create stories for the knowledge creation and track these just like any other story, and assign them to different team members; or
• Create another column on the story wall, right after “testing” to show which stories are awaiting documentation.

Lets assume that you decided to add another column to your story:

Then you might have an evolving release notes document that you build iteratively, and you would then hand the updated document over to production support each time you deploy into production.

Obviously, the contents of the release document will depend on the team, the system being built and other factors. It might, for example contain:

1. Release date.
2. Context diagram and data model.
3. A brief summary of the key changes being released and the benefit they bring.
4. A list of the stories that are included, together with defects being fixed.
5. New or updated instructions for monitoring, disaster recovery and service requests.
6. Known defects and workarounds.
7. Implementation instructions.

Do you really have to do all that?

Of course in some projects the knowledge transfer strategy consists of a post-it note on your desk and the implementation consists of calling out “hey Jeff, come and look at this. It’s the new convergalator I am deploying it so you should know how to use it”.

But the complexity of your strategy should not be a function of whether you are on an agile or waterfall project. It is a function of what you decide is most appropriate for you and your stakeholders.