Is documented Agile software an oxymoron?


“Working software over comprehensive documentation” – Agile ManifestoNowadays Agile is a widely used software development practice.

In addition to the many benefits of this approach, its “lightweight” approach to documentation is well known and can be quite appealing to developers. If the project is not so large in terms of time and/or people, then user stories, self-explanatory code and a set of tests could be enough.

However, as a company which was the first in the world to be awarded a Scrum Capability Medallion through the clear and straightforward assessment of our Agile practices, First Line Software has accumulated tremendous experience in agile projects of differing complexity and appreciates those circumstances when documentation is helpful and even recommended. We believe the following situations benefit from a more complete approach to documentation: 

  • When there is no or only a weak ALM tool (ALM – Application Lifecycle Management. The ALM tool should provide easy management and integration between requirements, defects, tests etc.)
  • When there is interaction with a variety of project stakeholders
  • When complex features are defined by a large number of use cases
  • When a project is long-term

Let us have a closer look at this problem.

When there is no or only a weak ALM tool: Not all projects can afford TFS- or Quality Center-like tools so project requirements, tests, and defects are often stored and managed in different free tools or Excel spreadsheets. This may be acceptable in a short-term perspective but when change management becomes more complicated, it requires much more effort to keep project assets clear and convenient.

A project wiki with high-level descriptions as meta-requirements, together with references to related user stories, mails, and meeting minutes could be an elegant solution in these situations. It will improve requirements integrity because it will be easy to see the whole picture. The team members will spend less time in clarifying requirements, so gaining in clarity we will also provide gains in quality. Moreover, it is convenient to have a single entry point directing project members to key procedures and project assets.

When there is Interaction with a variety of project stakeholders: Today many projects tend to involve a large number of stakeholders. These can be virtual development teams, teams from different business areas (e.g. Ad department, Support teams etc.) or both. They can use a shared project environment or have their own. Even if the stakeholders have access to the project environment, it does not mean they have an equal technical or process knowledge of it. This may mean you do not have a Communication Management Plan. However analysis of what information will be required and providing it in a clear and convenient form is an essential part of effective project collaboration. For example, for functionality which will also be used by other stakeholders you can prepare a brief overview of the features, specify the areas of responsibility, list what is done on your side, and the approach to integration including related testing and escalation points (which is usually a Scrum Master/Project Master but can also be another person).

The importance of stakeholder engagement is now recognized by even the 5th Edition PMBOK® in which the group of stakeholder-related processes has been moved to a separate knowledge area whereas it had previously been a part of Communications Management in earlier editions.

When Complex features are defined by a large number of use cases: A comprehensive ALM provides a convenient integrated view for requirements, implementation, test cases/automated scenarios and defects. However, would it still be clear enough after the 10th change of particular feature? Each change will be treated as a new user story. Remember, we are not throwing away any of the stories as they become obsolete because historical records are important input for many processes. In terms of PMI processes, historical records on similar projects are OPAs (Organizational Project Assets), which, for example, can be used to help estimate the duration and to plan risk strategies, etc. The general vision of the features not overloaded with the details will help the team member to see the larger picture instead of tons of small details and thus avoid many potential errors. It can be most helpful when they need to go back to an already implemented functionality to bring in some changes followed by thorough regression testing. The technical specs, describing the technical decisions, and the approach used in making certain key decisions (e.g. remote events, approach to DB design, etc.) will also add necessary clarity.

So the longer a product exists the more demands appear. A neatly organized structure of Product Backlog Items (PBI), elaborated user stories, defects and tests is not enough for a clear and concise understanding of the product features and functionality.

When a project is long term: Long-term projects may require adding new developers from time to time, even for a very interesting project. To simplify this on-boarding process it is suggested to document the key decisions, the rules and reasons. At some point every project goes to maintenance so when the project is handed over to the maintenance team it is always appreciated if the technical and business overview – in addition to the formal checklist- is provided.

At the end of the day even agile products need a high level of knowledge sharing, which is provided by the right amount and type of documentation. At First Line Software we try to ensure that in our Agile development the documentation matches the type of project as we have described above. In turn, this ensures that we have provided the right amount of business continuity for our stakeholders.

Documentation is not a burden. Properly produced, it is an effective waste management tool. It saves time and thus reduces future expenses. It reduces the impact of external factors. It reduces the number of errors. And it also lets our customer feel comfortable and secure while working with us.

But it is also important to be mindful that agile documentation does not guide the development. Quite the opposite is true: it often depicts functionality which has already been implemented and accepted.

In addition, it is a duty of the PM/ SM to share the value of documentation with the team. As a Servant Leader such a PM/SM should be able to influence the team by showing how it helps the team to achieve the goal and to make the value clear for each team member. And only when the team fully understands the goal, can it be scheduled, executed and accepted.

Lastly, the right amount of documentation reduces the losses caused by external factors and reduces the time to get required information. In turn, this keeps our stakeholders comfortable by declaring our ability to foresee the project needs and the value of the project process and knowledge. This results in working software and happy customers. And this is something we can all embrace!

Isn’t this the right approach for the customer centric software development company?


Talk To Our Team Today

Talk to Our Team Today

Related Blogs

Interested in talking?

Whether you have a problem that needs solving or a great idea you’d like to explore, our team is always on hand to help you.