One of the pillars of Agile manifesto is working software over documentation. Even though it seems like a clear guideline, like everything else in project management, this also has multiple interpretations. There is no consensus on what is the right balance.

Many developers while they are actively developing a piece of software and trying to hit deadline, documentation may not be considered more important than the software that they are delivering.

My personal experience on this has been that the amount of documentation a typical team wants depends more on the teams/managers. Unfortunately there is quite large gap between the amount of documentation each team feels comfortable with.

Based on my experience I consider following as the way to understand a given piece of software:

1. High level architecture diagram
2. Well defined test cases
3. Modularized and organized code
4. Well Documented PRs

Each of these topics can take up a whole blog or two but I will try to summarize those.

1. High Level Architecture Diagram

Without a high level architecture diagram it will be difficult for a developer to start the project. Obviously this will change a lot during the course of finalizing a feature so developer need to do their due diligence to update this. Agile recommends to push the documentation as late in the project as possible and that is for a good reason.

2. Well Defined Test Cases

I do have a confession on this. Ten years ago when I heard that test cases can act as documentation, I thought that is just theoretical. But now after working on multiple projects pattern is clear, tests are one important dimension of an application and test cases are part of the documentation.

With new test tools and the need to deploy application in different cloud scenarios, having solid test cases is a must and all that developers would need to do on top of writing tests is to just give them meaningful names and it can aid to understand the functionality of the project.

3. Modularized and Organized Code

This is probably not new to developers. As a developer we try to find patterns/layers in the code to understand it. A code where dependencies are not properly layered it becomes extremely difficult to understand the software and we try to resort to other forms of documentation.

4. Well Documented PRs

I feel like PRs are the only place where over documentation is not going to cause any harm. One reason of that is because that is as late as it can be to document the code that one has just completed.

For some teams the above may not be enough. Some of the reasons that team would want more documentations are:

1. Nascent Team
2. Changing Managers
3. Cross cutting application development
4. Ill defined Product and architect role boundary

1. Nascent Team

When team is its earlier phase, there is a lot of developer churn. If feature ownership is changing a lot and multiple developers are being assigned to a similar ticket then it becomes difficult for managers to do knowledge transfer of that ticket and they ask for more documentation. For enterprises it may happen very less but I have experience this pain a lot in a startup.

Solution: Focus more on teamwork. If the team is pairing the knowledge will not just be concentrated in one developer so a new developer can start collaborating with the existing dev.

A new developer should not rely on just documentation and codebase to get ramped up. In a healthy team they should be getting help from all the team members.

2. Changing Managers

I have experienced this only few times but when managers are changing, each new manager would like to understand current state of the projects. They ask for more documentation for a full understanding of the existing projects. Not all managers feel comfortable going through above mentioned places to understand a particular project so they ask for more traditional style of documentations.

If they are involved from the beginning of the project they tend to do that less because they would know the history of the project.

Solution: Managers should rely more on the developers for KT of particular project. Managers should be able to get the overview of the system from the high level architecture diagram but should be able to get more information from the team regarding particular project

3. Cross Cutting Application Development

From my experience when another team is directly impacted by code changes there seem to be more discussion about the documentation. If there is no standard in place, teams will not know how the new changes are going to impact them so they ask for various different documentations to understand different aspect of the project. I have seen this happen in more coupled code. For example if team boundaries are not properly defined and various teams are working on the same codebase.

Solution: Use interfaces or standard language to define the boundaries between each teams and document those interfaces. Decouple teams and repositories in sensible manner.

4. Ill Defined Product and Architecture Boundary

This also happens rarely but I have seen this happen. When product is concerned about how their feature is being implemented they start to ask for more documentation.

Solution: Have more communication between development and product team where they discuss openly about the boundaries. Dev team could start building trust by demoing product more frequently so that product feel comfortable about what is coming their way and ask questions regarding their concern.

Conclusion

At the end of the day there is a real loss of efficiency when the team starts to spend more time in documentation than in working piece of software. Agile teams need to be vigilant about the time they are spending in documentation vs development.

When team starts asking for more documentation than needed sometimes that point to actual team problem, like team may have started eroding trust within themselves and are relying more on documentation rather than direct conversation. Or team members may have felt that they were told different things are different times and they want it to be documented. Those problems may have to be resolved in a different way rather than spending time in documentation.