We demo deploying applications onto a variety of Application Servers and other Middleware, like for instance WebSphere/Oracle-Bea Application Server/Portal, MQSeries, HTTP Servers and so on… Sometimes demo-ing a story, like deploy application A to application server B can take 10 to 15 minutes. That means, for an hour of demo time we can not show every user story that we finished in our sprint. So we only show the important ones. But what happens when demoing a story can take up to 45 minutes? How can can we cram multiple finished stories into the hour?

Multimedia to the rescue! Whenever we have a story that takes a lot of time to demo, we record a screencast when we are preparing, cut out the long waiting parts and then show it as a movie. Please note; we only do this when we demo a user story where we have to wait for a long time. It also is important to tell the product owner and stakeholders that you are playing a movie that normally takes 45 minutes but has been cut down to 2.

Two months ago we worked on WebSphere Portal deployments. The story; Deploy Portlets, Update Skins-Themes-and-Screens and create Virtual Portal was implemented and added to the Fitnesse test suite. To prepare for the demo, I ran the Portal deployment test case. Fitnesse quickly entered all the necessary data into Deployit. (1 second) Then it hit the “Deploy” button and we were off! (sub 1 second). My Macbook Pro’s CPU fans started spinning up because the deployment to portal was taking place and after 45 minutes it was done! Before i started the test, i recorded my desktop/screen with my favorite screencast software ScreenFlow. After the test ran, i edited all the parts out of the recording where there was no activity on the screen. That left me with a screencast/recorded movie of about 2 minutes! Perfectly demo-able!

During the demo, we played the movie, we got feedback from the product owner and had lots of time left to demo other user stories. Of course we told the product owner that he shouldn’t expect the same portal performance (2 vs. 45 mins.) But that was very clear to him.

It might feel a bit like cheating because we aren’t showing the real “live” user story. But sometimes it isn’t practical. We want feedback from the product owner and stakeholders. The more feedback we get, the better and using screencasts/movies in demos helps us a great deal.

The mantra is efficient communication and more interactions. So when a new developer enters the Agile project (Scrum + XP based), pair programming, communication across the table makes a person comfortable with the new project environment. Instead of going through bulk of developer’s handbook and design document, conversations help to bridge the gap. However when you need to really need to refer some documentation, it’s always there. Also new developer continues to develop on top of whatever existing team has built on. So you see, knowledge transfer is seamless and relatively easier compared to any traditional project.

Think about maintenance phase now. First of all, application is already existing. You may not have to enhance it further. So the scope of learning while developing software is not there. You get a production problem and now you have to see in which part problem lies. Developers who developed the application may not be there anymore. You may be in a situation where you don’t have any knowledge base of the project. You may try hard to go through the application with source code analysis but a normal human becomes helpless analyzing 1 million lines of code-base in a complex project. Understanding application with source-code analysis may not be the ideal way in this case. So you see knowledge transfer in maintenance phase may be a lot more trickier than in normal development cycle.

What all is required in knowledge transfer?

Considering all these issues, I am going to talk about an approach for knowledge transfer (KT) used in one such complex maintenance project.

To start with, in generic terms, KT can be divided in following parts:

• Application Overview – 20,000 feet view on the project as a whole. Generally it needs to be described on white-board. Many of the times, this discussion gets recorded as video and becomes the documentation for new joinee
• Application Architecture and technical design – Again focusing on broad perspective of the application. But in this case, instead of taking a look from 20,000 feet, we dive a little deeper. Explained and documented in the same way as mentioned for Application Overview
• Sessions for knowledge transfer of different application components describing functional and technical aspects. Some of the documentation is available. Rest is improved with the understanding of each new joinee
• Scrum Process – How a team does the Scrum in the project. It may be a little different in maintenance project as it generally follows Type C Scrum. The documentation is generally available on project wiki.
• Demo of running application – Whatever you talk about theoretically, may not make sense if you can’t think it visually.

How do we do KT?

For doing the KT we adopted following methodology.

Set up the development environment

The first step a new joinee takes, is to set the development environment. Project knowledge-base should be prepared in a such way that time-waste is minimal. So one-touch build is recommended. Instead of getting project softwares from internet and wasting time, they may be available in the local repository. Similarly for setting up the project-environment, a screen-cast can be prepared which becomes handy instead of asking people for trivial things.

Study the documentation available

Before new developer gets involved with the knowledge transfer along with senior developers, he need to first study the documentation available in the order mentioned by project-mentor. It provides the initial impression of the application to the new joinee.

Create a wiki page defining schedule and review

Instead of doing the knowledge transfer on adhoc basis, it’s important to properly plan it using wiki pages. Here one plans for the time require from team members and schedule the whole knowledge transfer to be effective. Keep in mind to add some slack in the schedule for the new joinee to digest the information.

Team involvement in knowledge transfer

Instead of doing the knowledge transfer in teacher/student mode, it’s more about teacher+assistant teachers transferring the knowledge to a student. The basic reason of doing that is to reinforce the application concepts in the team. It’s good for teachers as well as for students. Depending on questions/answers, different perspectives come out while discussing a concept which is good for team in general.

Last person taking KT conducts the KT for a newcomer

It works pretty good to reinforce the project-concepts for a team-member. He becomes the main teacher assisted by other senior teachers. By having the healthy discussion on project topics, it works well for the entire team. So instead of having a team of one expert, there will be multiple project experts. The methodology mentioned, encourages the teacher to ask other assistant teachers their opinion on the available information. It gives almost every time a new insight in the knowledge. Sharing/discussing knowledge increases the knowledge itself.

Improvements in the documentation

Along with knowledge exchanged between senior developers and new joinee, a very important task is to document the gap new joinee could see in the available documentation. It’s simultaneous effort along with continuing knowledge transfer. It’s important because with the improved documentation in form of multimedia and written documents, next KT becomes even more easier.

Conclusion

As you can see based on above mentioned discussion, knowledge transfer in an Agile maintenance project is not same as may be a case in an Agile development project. It poses different kind of challenges to the team. Above mentioned strategy worked very well to handle the knowledge transfer of a complex project. Any suggestions for improvements areas are welcome.

Agile software development also gets translated into efficient communication, collocation and sitting in one room or same table and having conversations whenever there are issues. Some of the XP practices like pair-programming helps a new joinee to come upto the speed when she joins the project.

When you talk about effective communication and resolving issues in a team as and when they arrive, you lead towards a situation in which knowledge resides in the heads. People may not feel the need of documenting in detail as they seem to know everything about the project. You may end up in a situation where a new team doesn’t have “enough” documentation to begin with in maintenance phase. That’s why when one talks about “just enough documentation”, that “enough” word needs to be quantified.

In Agile software development we focus a lot on test-driven development and sometimes we say, code is the documentation. Somehow I don’t seem to agree with this argument. I don’t deny the fact that source code should be written in such a way that it’s highly readable and maintainable at the same time. So I do agree to this argument in literal terms. But when you want to explain the application to a developer, test-cases are too fine grained as concepts. The simplest thing to do is to explain the application on a white-board. Looking the applications from source-code perspective leads towards a situation where people are able to see different parts of the projects individually but may not be able to see the entire theme of the application. You can take a look at a very interesting discussion on this topic between Jim Coplien and Bob Martin.

Let’s take a scenario. Software development is finished and the application is up and running in the production environment. The application is bound to go in maintenance phase after certain time. What happens when you don’t have any developer in maintenance phase who worked on this project in development phase? You get into a lot of trouble. A lot of things like certain design decisions, functional aspects begin to look hazy.

What makes the life of a new developer easier?

When a new developer enters in a maintenance project, instead of looking directly into source-code, he’ll definitely want to see the project in its entirety from 20,000 feet. It may mean to get the idea about what the application is all about in holistic perspective, its functionality, stakeholders, interfacing points and the value of the application in business terms etc. It may be followed by a discussion on the architecture fundamentals of the project and then going into technicalities and functionality of each component. Depending on the parts the new developer need to focus on, she can be given details about those components individually. After that for sure she can dive deeper in the source code. It makes the life of a newcomer a lot easier as introduction to something new happens in gradual process and not from a “blind man looking at elephant” perspective.

How do we actually do it?

Before we talk about how we really do it, let’s make our assumption very clear that we want to reduce the number of project-veterans in a gradual phases. It seems quite inevitable as most of the people want to look for yet another life after a long project. In the end it should reach to a situation where old developers have minimal or nothing to do in maintenance phase. So it makes sense to proactively induct new people in the project in phases while releasing the veteran developers from the project. Essentially, end target should be a totally new team going into maintenance phase. Ideally it makes sense to think in a way that there will be no support available from old developers in maintenance cycle in ideal case.

You may say that when you recruit new people in phases, the velocity of Scrum sprint may go down. There are two aspects to it. One is – customer should be aware that reduction in team velocity in inevitable but in the end, it is going to prepare a team and set of knowledge base which will be good for them in maintenance phase. Another way to handle it is to recruit multiple people when an old developer is removed from the project. This scenario makes sense from financial point of view when you are trying to outsource the maintenance phase to a distributed team.

Just now we talked about what all is required to be effective in maintenance phase. Now let’s talk about how to get it done and be prepared for it in development cycle itself.

First of all, based on our analysis to ascertain what all documentation is required for maintenance phase, we need to conduct a gap analysis. Based on the gap identified, the documentation can be done in innovative way. As discussed in one of Xebia blogs (underlines the importance of multimedia usage for documentation), when we want to do something like project overview, it’s good to do that on a white board followed by a question answer session from new joinees and get it recorded as a video. The same can be done for knowledge transfer of architecture presentation and application functionality. Instead of doing knowledge transfer for each joinee, it’s good to get the content recorded.

When one wants to dive deeper in application functionality, there may be documentation available to cover the functionality and technical aspects of different parts of application. Whenever required one can also use screencast also for installation guidelines. Along with high-level documentation available in form of videocast, written documentation for individual components gives a very good start for a new developer.

As new developers join the project in the last phase of development cycle, they first refer the already available documentation (videocast and written). If they find any gap, they refine it further. Now the documentation which we are talking about right now is “just enough” by definition. No thick volumes of documents. However it should be sufficient for a new Java developer to come upto the speed with the project. As project moves, old developers leave project, new developers join and enhance the knowledge base, based on their own experience, problems faced with available knowledge base.

Conclusion

With this documentation and knowledge base in hand, it becomes relatively a lot easier for the new team to go into maintenance phase without much hiccups. Even though so far we have been talking about no experienced developers in the end in ideal scenario, in reality it’s always good to have an experienced developer available for 1 day in a week to clarify issues if any for initial phases.

- Why screencasting is useful.
- What are the steps to create a screencast.
- How to release the screencast to your intended audience.

There will be a technical explanatory video following this non-techy episode very soon.

So head on over to the show page or subscribe to our podcast!

- How did they get into multimedia
- How did they introduce it to Xebia
- What were the reactions
- What are the differents formats and concepts. (Podcast, Vodcast, Screencast, Comics, Whitepaper video etc….)

In the near future they will provide different Vodcasts where they show the different formats, including howto and where you can apply them.

So head on over to the show page or subscribe to our podcast!

What do you do then? People who were in the project at the beginning may not be there anymore, either from customer side or from software developers side. Without having a knowledge repository, new people will try to reinvent the wheel, will go through the code (white box, which ideally should be a black box most of the times) or will look like people who enter in a dark tunnel without having clue on what they are supposed to do.

So, we know that we require a good documentation and we also know that people usually don’t want to do that – just because it’s not interesting enough. It may be mechanical and you may not be the magician of the words so you are able to articulate a story in just-right words. Also, to write one story you may take a whole day or even more. So we know it’s required but it’s a tough deal.

From reader’s point of view also, nobody wants to read 100 pages of documentation. Ever wondered whenever we want to know about something, we want to get the shortest possible way and that’s to ask a project-expert. Why? It’s more interactive, it’s more visual and you can relate to that communication very easily and within a very less time. For the project-expert and for the new developer it takes a lot less time than writing or reading 100 pages.

So you know what – we know what we require in terms of documentation but question remains – how do we do that? The answer is – by using multimedia communication. There are various low-tech, low cost/no-cost softwares/hardwares which take a lot less efforts to setup and having screen-cast, video-cast, pod-cast made up quickly. The documentation which you may take 2-3 days to complete, is finished within 15 minutes of presentation with voice and video. When we talk about low-tech, we implicitly are talking about softwares which cost nothing or very less license cost. We may not be trying to make a very professional and perfect presentation but a presentation which makes sense. So instead of having a high-end video camera, lights and all that jazz, you may be comfortable in having some pages and a marker and a high-definition camera and a microphone. That’s all you need. Similarly there are various open-source softwares available which do not require any cost.

Again multimedia may not be good for every communication. The communication has to be very simple and straight so that audience are also interested to watch it. Complex content, frequently changed information, legal/official documentation may not be the candidates for multimedia. However it holds good for many cases. For instance while explaining design/architecture you may talk about a lot of stories/histories which may be part of your rich experience and which may not come as part of written documentation. You may start drawing one single box and the integrating it with multiple boxes while providing providing overview to diving into details. So the whole thing is finished in 30 minutes/an hour which otherwise would have taken 2-3 days to document and half a day to read.

However there needs to be a balance of written and multimedia documentation. Written documentation provides you the capability to make things more concrete and to-the-mark. When you really need to dive deeper, you need it. For instance, you may not want to explain the database fields and remember them. They need to be the part of reference written material. However when you talk about explaining things in general, telling stories/histories, why we did this/that or explaining sequence of steps, multimedia documentation is more helpful.

Written documentation provides you the capability of indexing the content because of obvious reasons. If you have a long multimedia presentation, it will be difficult to index for a content. So it’s advisable to create short presentations (10-15 minutes). It’s also good for author as well as it provides him a mean to focus on the things more than if he has a long presentation. You may have found a Scrum principle working here . Usage of small sprints and be focused than having a big backlog for a large sprint with no focus at all.

Multimedia is all fun. People who develop and who use it, like it very-very much. It’s always cool to create a podcast, screen-cast and video presentation for people and it’s really nice to go through such material. Don’t you think?

So you know what? We can have just-enough-documentation with really “Agile” way of doing it. No more abstract/vague definition anymore. The combination of written/multimedia documentation really helps people in right way.

P.S. I would like to acknowledge the contribution of some great conversations I had with Multimedia gurus Serge Beaumont and Robbert van Loghem before I could write this blog.