Minimum-documentation is one of the basic features of agile development (intuitive GUI, visually rich documentation, automated tests replaces it). But usually software development goes hand in hand with the development/reengineering of business processes and (in opposite to agile software development) the introduction and the implementation of the business processes require detailed and throughout documentation. That being said - can software developers expect that business processes that are mentioned in the user stories are well-documented and that the business documentation for business processes can be used more or less directly in the design and development phase?

I have sad experience that sometimes there is little rethinking and little documentation of the business processes themselves and that makes development and maintenance of software quite hard. Sometimes it happens that the definition of business processes occurs at the same time when the requirements for software are defined. It is quite strange. Because business processes should be defined at the higher level of the chain of management.


3 Answers 3


This is a rather unusual interpretation of “Working Software over comprehensive documentation” value. This value of Agile manifesto was created as a reaction to the projects where documentation consisted of hundreds or thousands of pages of documentation nobody would care to read; the goal was to replace those huge and hugely useless manuals collecting dust on a shelf by something closer to developers, something more accessible, more readable.

Of course, some of documentation can be replaced by user stories and automated tests, as well as clean code and clean architecture—two critical aspects you haven't mentioned.

This being said, there is still documentation to do, whether the project uses Agile methodologies or not. Some projects would require only a few pages describing how to install and use them, as well as their architecture. Others would still need a lot of documentation, because original developers came with non-intuitive but necessary design choices, because the project relies on some quirks of a third-party system, etc.


  • Document thoroughly.

  • Don't write documentation for the sake of writing documentation.

  • Carefully chose the best format for a piece of information to document. Sometimes it would be a test. Sometimes it would be an UML diagram. Sometimes, it would be a better variable name. If other developers read your documentation, you succeeded. If it collects dust on a shelf, you made a wrong choice.


Process documentation only has to be written once. If that's a requirement for doing business either within your company or with your client, then that work is part of sprint 0 (i.e. the very first sprint). I've been in that position before, and was able to map agile processes into CMMI level 3 with no tracking documents we would have otherwise had to create routinely.

Agile is not about replacing the requirements to do business, it is an approach to tighten the feedback loop to be able to correct for problems early while they are still small. It's an approach that encourages experimentation so that you can find the approaches that make your customer happier.

There's always an impedance mismatch when you have to fit agile within a larger waterfall style process in your customer space. That's where you have to set up firewalls for where one ends and the other begins. That kind of environment lends itself to a dev-and-hand-over-to-ops rather than a straight DevOps approach. It's also specifically these types of things that you need to document in your process write up. That lets your team know that if the customer wants something by some date, you know exactly which sprint you have to have a full releasable package to put through the larger process.

Most people have to deal with less than optimal situations. Even though Agile's been around for a couple decades now, it's still viewed as the young upstart process. The goal in documenting your process is to make any artifacts that the people requesting you write your process want to see a natural byproduct of following the process. For example, tying every commit to a requirement or bug report is easy since most issue tracking systems handle that for you as long as you reference the issue number in your commit message. Getting a report of what is done and how close you are is a matter of having that tool generate the charts, etc.


Let's be frank, If you have a requirement for extensive word doc style documentation It doesn't. Question the requirement.

But! As well as being a step down from big waterfall process software development, also remember that agile is a step up from chaos no-process development. If the docs are a requirement then put them in the backlog, prioritise, estimate and schedule as normal. The cost then becomes visible to the customer.

  • Your first statement is really hard to parse "If you have a requirement... It doesn't". What does "it" refer to in this statement? Commented Oct 12, 2018 at 13:29
  • :/ yeah, I really dont want to add the question though.
    – Ewan
    Commented Oct 12, 2018 at 13:34

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.