Working software over comprehensive documentation

Working software over comprehensive documentation

docDoes the title sound familiar? This is the second point listed in Agile Manifesto. Do you remember about it everyday at work? Do you really understand what it means and why it is so important? I am sure some of us do not because I have met two such persons in the last couple of weeks :)


Stop doing Waterfall in Agile

When I started my career, I worked as a database developer in a Waterfall environment. We had to describe each stored procedure and function in the script's header with author, creation date, purpose, input and output parameters. Additionally, each development had to have a business and technical documentation no matter how small and straightforward it was. I did not challenge the need of such documentation and I did not see anybody else doing that. I was taught Waterfall at university and comprehensive documentation was a big part of that methodology. That did not seem weird to me at all.

Later, I heard about Agile which questioned multiple Waterfall rules and practices including documentation. It all made sense - spending huge amount of time on maintaining documentation which is not needed is a waste of time. For new comers in Agile, the methodology seems to resign from the documentation completely which is not true by the way. But creating pages of technical documents that nobody reads is following Waterfall not Agile.


Documentation in Agile

First of all, documentation is not useless by definition. Some types in some cases are. Working software over comprehensive documentation means that delivering software that does what it should comes first in the priorities before creating documentation. If for some reasons you have to choose between those two because of time constraints, choose spending time on software development rather than on writing documentation.

On the other hand, Agile does not say that you should stop creating documentation completely. Some documents may make sense for you and your company. You need to analyse which are needed and which can be dropped. In that context, next time when you are going to create a document, hold on for a minute and find out who needs this document and why. If you are unable to find convincing answers, there is a huge probability that nothing bad will happen if you do not deliver that paper and spend your precious time of something else.

Next, I will provide you with some common cases.


Technical documentation

Waterfall insisted on creating entity relationship, class, integration, interaction overview diagrams and other technical documentation before starting the implementation. Waterfall gurus believed that only experts could decide on architecture or even public methods of Java classes so such documentation was necessary to show regular developers what structures they should create in the code.

Now, it is done in a different way. Agile favours emerging architecture and incremental changes so the need of designing Java classes by architects is no longer mandatory. If a developer needs a diagram to visualise the concept before the implementation, that is fine, but it is not required in the methodology any more.

Why you should avoid technical documentation:

  1. It is hard to keep it up to date. Outdated documentation is worse than no documentation.
  2. It is impossible to keep it complete in the long run. Source code contains multiple IF statements. I do not believe you are able to include them all in the paper. The same as above - incomplete documentation is worse than no documentation.
  3. The only source of technical information that is always up to date is the code itself. Stick to it. If you needs documentation because it is difficult to get information from the code, clean the code. Good architecture is easy to understand and to follow.
  4. Developers hate updating technical documentation and they will avoid doing that which will result in outdated and incomplete paper. On the other hand, hiring a non-technical person to maintain technical documentation is wrong by definition.

Of course, you might have a case when some kind of documentation makes sense. If it does for you, create and maintain one.


Business documentation

20 years ago business analysts produced business requirement documents (BRD) and functional requirement documents (FRD) to have the arrangements with the client written down before engaging developers. It was that way in Waterfall. Agile requires Scrum team to work on a user story which does not describe the functional requirement but a user need or a problem. Scrum team should deal with a pure user issue not just implement what is written in FRD.

Why you should avoid business documentation:

  1. Whatever is written in the documentation, that will have to be implemented because we promised it to the client even if you realize later that the client needs something else.
  2. After implementing a feature, the paper is useless because its purpose was to provide requirements to developers for implementation. I know, someone may tell you that you can refer to it in the future to prove that your product works as agreed. But really? Is it the way how you want to work with your clients? To argue what was in the paper not whether it really solves the business case? Agile is about delivering software that has business value not what was in the contract.

Of course, you might have a case when some kind of documentation makes sense. If it does for you, create and maintain one.

Do not miss valuable content. You will receive a monthly summary email. You can unsubscribe anytime.

End user documentation

When I began my journey with computers I used Windows 95 and I remember how I hated accidentally pressing F1 key on my keyboard. The whole system frozen. After a few minutes a message box appeared with information that help content is being indexed and I should wait. Then I was able to finally kill the process and go back to what I was doing. I do not remember using built-in help in programs. When I do not know how to do something, I use an internet search engine to find an answer.

If you struggle with writing user manual, think about creating a users community, a forum where they could exchange information how to effectively use your software. I know, it is easy to do for programs that is used by millions of users, but even for applications dedicated to a narrow group of people, it is doable. It will require your engagement to answer users' questions and to keep the community active but I am sure it is more interesting job that writing a document and definitely better for users.

Why you should avoid traditional end user documentation:

  1. Users dislike reading manuals. Advanced users prefer using internet search engines and forums to find answers and tips. Novice users will expect that the application is intuitive and will not read a manual anyway.
  2. Nobody wants to write manuals. Collegues would hate you if you asked them to do so.

Of course, you might have a case when some kind of documentation makes sense. If it does for you, create and maintain one.



With Scrum you do not have to create and maintain documentation. You may consider it and make a concious decision which documents are worth to keep in each case.


Looking for more information about Scrum?

Idea behind User Stories in Scrum

Do not estimate bugs in Scrum!


Video version:

If you like what I do, consider buying me a coffee :)

Buy me a coffeeBuy me a coffee