Agile way of documentation!!!
Posted by ShriKant Vashishtha in the late afternoon: May 5th, 2008
As you enter into Agile world, a statement welcomes you - "Just do enough documentation". For quite sometime, I was puzzled what we really mean by this. In my view "just-enough" is very ambiguous or abstract. You cannot quantify it. For some who are working for a development project, creating documentation may not make much sense as you can find people just across your table to answer your question and you can get away by doing "not just-enough documentation" (no java-docs, no project overview etc). However when you come in maintenance cycle of the project, it just sucks. Maintenance may implicitly means new people, a long project cycle and people who leave the project or even organization itself.
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.
Archives
Training
Xebia Sites
Categories
- Java (279)
- Agile (109)
- General (50)
- Testing (42)
- Performance (42)
- Hibernate (36)
- Scrum (33)
- Podcast (31)
- Architecture (31)
- Spring (28)
- SOA (24)
- Maven (22)
- Project Management (22)
- Flex (17)
- JPA (17)
- Eclipse (15)
- Quality Assurance (14)
- Middleware (19)
- Frameworks (13)
[...] 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 [...]