Agile documenting


Original in my employers blog–combine-waterfall-and-agile-project-methods–save-time-and-money/

Project model – combine waterfall and Agile project methods – save time and money

Many times customer wants to buy projects in waterfall model. Even if the customer knows the pros of an Agile method they still want to have fixed scope to ensure the delivery of a project. This means that the project is done with waterfall model and contains separated design and implementation phases. Customer buys first design phase and estimations before the actual implementation phase. I integrated internal Scrum agile method to this process to save time and effort in both phases.

In this case design phase deliverables are functional specification, visual look and feel, wireframes and technical specification. Design starts with the requirements and functional specification. Between workshops the functional document and wireframes are done. UX designer will be used for the layouts. After this is time for the technical document.

Traditional technical document lacks the actual design of technical implementation work. This practical design will be done during a project usually. It means transforming the technical document into Agile backlog in the implementation phase. The problem is now that we need this information for calculating the estimates. We need to know “how” the solution will be done. We need to give a price with minimum risk for the supplier and with competitive price to buyer.

The solution is to slice the system into smaller bits in the design phase like in Agile method. The order between these bits (features) needs to be prioritized anyway. It can be done before implementation. The first chapters in the technical document will be the same as in the traditional technical document. These first chapters cover the overall structure of the system to be build. The rest of the document is in Agile form. This means that chapters are written into backlog form where main chapters represent biggest features (product backlog items) and subchapter presents smaller features or actual tasks. Third degree chapters can represent technical tasks in detail level.

The Agile form chapters are called feature chapters. They are in the same order that they should be developed – just like in the product backlog in Scrum agile method. There is logic between the chapters. Some part of the system needs to be developed before other modules can be developed. This means that the design phase goes like in the Agile project model. Except there is no work between designing features. Architect needs to do this work in his head anyway when making estimations. Why not do it formally and document it right away. After document is ready the project have a product backlog ready to be estimated.

This document can be held to a developer team for estimations. These estimations will be very precise because there is already answer how it is done. This reduces the freedom of a developer solutions but gives more accurate estimates. It may also challenge developer in the implementation phase invent faster way to develop a feature or solution.

The implementation phase project model will be Scrum. Even it is sold as waterfall. A task for the documentation will be added to the Definition of Done (DOD). This means that the traditional technical specification builds up same time as the system. When the project is done so is the finalized technical document.

Saving time

  • No need to transform technical document into backlog in implementation phase
  • No need to design the order of backlog items (features)
  • No need to use architect work while transferring the technical document to product and sprint backlog
  • No need to create traditional technical document beforehand


  • to calculate workload estimates in design phase when technical specification is already in  modules
  • to decide which modules to be taken into implementation
  • to know which modules needs to be done (must have)
  • to know what are the relation between modules (must do this if want this)

This does not mean that architect should not work in the implementation phase. The main idea is to do the practical design beforehand so that workload estimates are more accurate. It is challenging for the architect but this way we prevent doing duplicate work and giving estimates that did not consider technical challenges which come up in the practical design work.


Example of workload estimations. On the left side there is a general list of modules in the project. It is the list for estimations in the traditional technical document. Architect and developers can add there estimations but they don’t actually know anything about how the system will be built. Estimations are based on guesses. On the right side there are feature chapter estimations from the technical document. Architect and developers can check what and how each chapter functionality is meant to be built. They also are in the prioritized order. When last feature is done the project is done. Project leader can rely that this estimation contains all the work to be done. It also means if estimations differ from the reality during implementation, project leader can acknowledge the possible delay in the early phase of the project.

This is not a silver bullet. It is always better to do the project fully with Agile method. If there is no possibility to do that, then I will use this model.