Be agile and bring documentation to life

bart-simpson-generator Image credit:

Agile approaches follow iterative divide-and-win strategies, based on fluent communication, incremental work and continuous feedback. The Agile manifesto states that “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.” However, the principle “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation” does not hold true in many projects because of time pressure, distributed projects, team changes, strict regulations,  large-sized applications, huge domain knowledge or complex organizations, etc. In some contexts, face-to-face conversations may not be enough (or not always possible), because “faces” may change, may become unavailable or may simply leave the project. Moreover, if the knowledge is spread out only across different minds, then the whole picture may be lost. In these situations, communication mechanisms need to be enriched with explicit knowledge specifications. Taking this into account, a question arises: can we use accessible, centralized and explicit repositories of knowledge as an accelerator for Agile approaches? The answer is ‘No,’ if documentation is too ambiguous, ill-maintained and bureaucratic. But, the good news is that the answer can be ‘Yes,’ if documentation is ‘alive.’

What does “alive documentation” mean? Documentation is alive if it is executable by simulation, it’s non-ambiguous and can be (easily) changed as a reaction to frequent alterations. Documentation may be a drawback for agility, if we conceive it as a set of non-updated and unstructured collection of words with ambiguous meaning, because its utility is limited and usually becomes dead. In other words, we don’t need Shakespeare for documenting system knowledge. However, agility may be supported, if we are able to manage structured, concise and easy-to-update specifications that support knowledge discussion at each iteration. If we have a useful map, we will find the right way faster. What if we were able to structure system functional knowledge in models from which we could generate purpose-driven documentation that could be easily regenerated after changes? This is not the future, this is the present (watch the Recover webinar  for details).

Establishing a purpose-driven modeling strategy, for managing knowledge in Agile projects, is essential for enhancing the potential of many other principles of agility, specially about change (“welcoming changing requirements even late in the development”). It’s because models facilitate impact analysis and detection of early inconsistencies , in addition to reporting and estimation facilities.

In summary, the claim is that “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software” but we also need to add associated knowledge representations in the form of weighted models or documentation. In this way, during each iteration, the piece of working software becomes a part of the result, and this piece of documentation is integrated into the global specification view for better agility through enhanced knowledge management.


Albert Tort


Albert Tort is CTO of Sogeti Spain. He is a software engineering and testing & quality assurance specialist.

More on Albert Tort.

Related Posts

Your email address will not be published. Required fields are marked *