It’s common sense in the agile community that design is emerging during the development. Some extremist state that modelling before coding is not necessary at all. Well, that is not true. But is it necessary to create design documents to capture the models?
Every problem solving for even a little complex problem is done by an evolutionary process. Evolutionary means that variations are created and the best variant is selected. If design is a solution for a problem, then the process to get to a design will look like this:
- The developer creates variations of possible solutions in his brain. By playing virtually with it, he finds and selects the best solution.
- Then the developer will collaborate with other developers and compare the possible solution. They select again the best solution or may even find a better one. This step creates a common understanding.
- The final step is that the solution is put into the code. That really proves it and the common understanding from the second step will help if multiple developers implement the solution. During this the solution may even be amended iteratively by going back to step 1 and 2.
First of all it’s important to note, that the inital step is to create a possible solution in the brain of the developer. That requires creativity and experience. Good developers will come up with good solutions. But nobody is perfect and other developer with different experience may come up with other solutions.
In the second step the solutions can be merged together. That works best with synchronous collaboration and a modelling technique. An asynchronous review process (send review comments via email) is inefficient. Also, developers can come up with solutions that wont be selected – they are wasted. It’s a nature of the evolutionary process that variants are wasted. The question is, how much effort has be invested into the variant and is it possible to create a variant with less effort.
The third step will transfer the solution – at this point it is only an idea of a solution – into the code. Only with the code the solution becomes real.
In which part of this process do we need design documents? While a developer thinks about the solution, he can write it down. That can be done with a word processor, modelling tool or paper and pen. He is maybe so bright that he actually don’t need to write it down. Given that in the second step the solution variant may not be selected, he should invest not much effort. But he needs something to show the solution to others. In the ideal scenario, he has it in his head and draws it on a whiteboard by talking to others. After the second step the developers may want to fix the common understanding, because it may take some days to implement it. You could take a white board photo and store it on the wiki. After the third step the solution is in the code. The common understanding may have changed a little.
The light weight documentation (paper/pen, whiteboard, photo) may not be useful when you have large systems and bigger changes. But that would require a more high level design, aka architecture. An architecture is more long term, may change but not quickly. Also a developer cannot implement the architecture in a few days. It is more a guidance for lower level designs. Architecture and high level design documents can be reasonable. And – documentation for later maintainance is reasonable as well. It depends on the effort to what level starting from the highest level you want to create the documentation.