If you have read the agile manifesto, you’d have definitely noticed the second line “Working software over comprehensive documentation”. So, what does this mean? No documentation at all, or few documents here and there - just for the sake of it! I am sure, you’d have faced documentation related problems somewhere during a project. Take this scenario for example - there is no documentation for a particular module, and no one has the time to explain it to the new developer who just joined. Now, you have boatload of work to be done (and so a new developer) but new joinee can’t work (at least not very fast) because no one is free (remember the boatload of work) to tell him how to work.
Of course, you followed the agile manifesto - but what about such situations? They surely deserve to be nipped in the bud, and so, it would have been great to have some documents to help the new joinee here. But, the problem here is of sheer pace at which teams work, they forget and sometimes even ignore documents because that is not in the tasks list.
Photo by Florian Klauer
So, it is obvious that there is a need for some kind of documentation and that, agile manifesto doesn’t say that you should not document at all, rather it means that if there is a confusion about priorities, the item on the left (working software) should be given priority over the item on the right (comprehensive documentation). Lets look at a few possible solutions about how to get different types of usable documents while teams are busy developing software:
- Source code comments: There is this famous saying among the developers “ source code is the best documentation” - that may be true for developers or someone who knows the architecture in and out and can read the code. But for new joinees or people who can’t read code, inline comments in source code are the best bet. Now writing comments in the source code is more of a habit/choice than software development methodology dependent thing. It doesn’t take much effort if done while coding and makes for great, to the point documentation.
If you can develop this healthy habit of writing comments in the code - half of your work is already done. You can then use tools like Doxygen or Javadoc to create documents out of the source files.
- User manuals: While new joinees to the team will have great time reading the source code comments based document, the end users will not. They are not really bothered about the architecture of your software, but just how to operate it. Unlike the architecture document, a user manual needs a more friendly tone and should be clear about the steps to follow to achieve a particular outcome. So, it is very important to have a user manual written specifically keeping the use cases of end users in mind. To achieve this, you need a someone who is passionate about the software and the end users - probably a volunteer from the development team or a dedicated author. After the author is finalized, you need to track this, and the best way is to probably add this as a task in the task board and keep an eye on the progress.
There are companies that consider their software so easy to use - a manual is not required. If you are confident and ready to take this risk, go ahead. You will, for sure get to know if at all users can use your software.
