I recently had an MRI on my knee. The report was full of words like joint effusion, medial patellar plica, acute medullary bone contusions, and medial femoral condyle. While my doctor could easily read and interpret the report for me, my attempts to understand the report were doomed. This, in part, underlies the problem with documentation–the difference between context and content. Documentation can provide content, but understanding the context requires domain expertise. Knowledge sharing and documentation are definitely issues when scaling agile.
Documentation isn’t the issue, understanding is. Do the developers understand what the customers want? Do the customers understand what the developers are building? Do testers understand what the developers intended to build? Do software maintainers understand what the developers built? Do the users understand what the system does for them? Understanding takes a combination of content and context, and documentation is a poor conveyor of context.
Understanding comes from a combination of documentation and interaction, or conversation–the conversations among people who have a certain knowledge. In a complex situation, documentation by itself may provide only 15-25% of the understanding required.
The Agile Manifesto “working software” principle has two critical components. First, it says that working software is critical to measuring real success, but it does not say that documentation is unimportant. Second, the word “comprehensive” denotes “heavyweight” rather than lean documentation. Documentation necessary, it’s just not sufficient. Agile developers are not anti-documentation, but they are practical about what documentation can realistically accomplish.