Unknowntttt copy

How does the traditional functional and technical documentation work in Agile?

July 3, 20172 min

In Scrum and Agile, there is not much guidance given on functional and technical documentation.  The Agile Manifesto states that Agile teams value “working software over comprehensive documentation.”  That provides clear guidance on what is the focus of an Agile team, but is not a helpful answer to the question.

Looking deeper into the Agile principles, the authors of the Agile Manifesto share these two ideas which could be helpful in thinking about documentation: “working software is the primary measure of progress” and “the most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”  For people who lack direct experience working with Agile teams, these statements seem to reinforce the myth that documentation is unnecessary for Agile teams.

However, in my sixteen years of working with Agile teams, this myth is completely untrue.  Agile teams have plenty of functional and technical documentation, but it is different than what people expect if their organization has a long history of industrial processes.  In a traditional organization, most of the documentation for the design, requirements and technical specifications is created up-front and approved BEFORE any code is written.

Agile teams take a different perspective.  Documentation tends to be an outcome of the working software.  Since the code is considered the design, most of what is needed to document the software, from a technical perspective, will be in the source code and the automated unit tests.  This is why Extreme Programming places a strong emphasis on test-driven development and merciless refactoring to achieve a simple design.  The various automated tests serve as an executable specification of how the code works with various examples.  Some people say these executable tests act like the system specification.

However, not everything one needs to know about the software can be kept in the source code and the tests.  High-level design diagrams, design briefs\narratives, information flows, roadmaps and use cases are examples of other types of the documentation some products find necessary.  The amount of documentation an Agile teams needs depends on their domain and consequences of failure (comfort, discretionary money, essential money or life).  For these other documents, I recommend creating them incrementally and use them to document what was created, not what is to be built.