The problem with Agile and Documentation

During my years of experience in different types of team setups, I observed a tension between agile methodologies and documentation.

Just to remember the agile Manifesto:

1. Individuals and interactions over processes and tools

2. Working software over comprehensive documentation

3. Customer collaboration over contract negotiation

4. Responding to change over following a plan

The particular problem I noticed was: "Working software over comprehensive documentation". This written sentence was often used as some kind of of bible to argue down a demand for documentation.

Why its a problem to underestimate documentation?

To understand where it starts to be troublesome I need to briefly differentiate types of documentation

• comprehensive documentation that specifies all design specs and technical functions

• relevant documentation that provides the necessary information for the target audience to work with

Neglecting documentation, particularly relevant documentation, can cause issues that are not immediately visible.

It's not scalable

The lack of documentation makes it difficult to scale information within the organization. For example, passing information to a new team member or other departments would require a significant amount of time and effort.

In my recent years I figured I spent 10-15% a month just on passing, preparing or explaining product topics to externals.

When you got a good documentation behaviour you can just pass the link and in question you can follow up with the requester. So you enable others to help themselves!

Works specifically not for complex products

I worked on easy to understand products and on heavily complex products. If you don't do product documentation even the team has problems to quickstart discovery topics because they need to start understanding again how the product works in this area. With a relevant documentation you have a much faster kickstart and you are able to dive into specifics directly.

Blocks others

As in "not scalable" already mentioned. When you got no accessible source of information you will block everyone in and outside your team in decision making and understanding so they need to reach out everytime to you, need to find a meeting slot, need to write things down for themselves and so on.

With a documentation you can enable others! For example: You are working on a search product with tons of relevance factors which in the end define the results shown. You can write down which are the factors, what is the weighting and give examples. So everyone can get a first idea why specific results are on top (for sales and customers interesting to understand) and other product managers know which fields in your product are indexed and could be used for ideas build on this data. Without this page you would need to explain it all the time, and not only once because people will forget after a few months.

It's just stupid

Furthermore, a good documentation behaviour can help save time in the long run. For example, when employees are sick or leave the company, their knowledge and information leave with them, and colleagues may struggle to fill the knowledge gap. However, with documentation, everyone can understand the product at least at an important level.

Conclusion

In conclusion, Agile methodologies do not mean abandoning documentation altogether. While documentation should not take priority over working software, it is necessary to ensure that relevant information is accessible to everyone who needs it.

How can I establish a good documentation behaviour?

I know documentation sucks and it is another thing to do on top of the schedule. But as mentioned it will safe you time on the long run!

Here a few tips how I managed to establish a documentation behaviour:

• reduce the time needed to do documentation: create templates so the documentation follows an easy repeating pattern. This will help you to be fast in setting documentation up and will also enable everyone else to understand each documentation fast.

• gather questions you get a lot of times, that is a very good indicator what should be documented

• set yourself a timeslot when you want to revisit documentations so you keep them up to date, nothing is worse than an outdated documentation

• set up a structure to find documentations you own and you need to revisit once in a while. I use confluence and set tags in this structure: owner_myname , occurence_monthly So all of my pages are listed under the owner_myname tag and I can see which pages I need to revisit an check in which occurence. Once a week I revisit the needed pages and briefly update them if needed. That's much more efficient and easy than updating all pages after half a year.

• define ownership also for other parts of the product you are not able to maintain. Without ownership nobody will feel responsible to do so.
  

To read more about the topic you might be interested in: