Documentation in agile methodology
AGILE PROJECT MANAGEMENT BLOG
MINDSPIRE BLOG
Follow MINDSPIRE on social!
Introduction
It is a common misconception that documentation is not required during agile software development.
In this post, we will examine the basis of this misconception, its justification based on the agile manifesto, and why we believe that properly and adequately prepared documentation is needed.
Topics of our article series
1. Overview of the agile squad
2. The agile user story
3. Measuring the performance of the agile squad
4. Agile ceremonies with a practical eye
5. Documentation in agile methodology
6. Let’s break it up, or what is incremental development about?
7. Backlog or Blacklog?
8. The importance of agile operations and sprint planning
9. Long-term planning in the agile operating model
10. The agile organization with an HR perspective
11. Agile operation in the shadow of the home office
12. The challenges of agility in an enterprise environment (planned)
13. Where should agile operations be used? (planned)
Is it possible to get rid of documentation with agile?
Let’s face it, no one likes to document, most people think it’s a waste of time. The general perception is that there is never enough time, and usually the right methodology and supporting tool is missing. Besides, the task itself is boring and the resulting documentation of dubious quality is not read by anyone.
That’s why, when agile methodologies started to spread, the banishment of documentation was one of the strongest calls to action, helping to convince even the most resistant to change that it was worth taking the leap, as a much brighter, documentation-free future awaited them.
And it worked so well that, to this day, you still regularly hear teams in “agile” organizations say, “We don’t document because we are agile!”
What is the basis for the common perception that documentation is not required in agile?
But where does this very strong misconception come from? Why do most people who have encountered agile ideas in any form think that documentation is not necessary in agile?
One of the four values in the agile manifesto is “We have come to value working software over comprehensive documentation”.
This is further reinforced by the agile principle that “The most effective and efficient method of convaying information to and within a development team is face-to-face conversations.”
Based on these two statements, many interpret agile as:
- in the agile user story, these three questions “To whom?”, “What?” and “For what purpose?” must be answered in three complex sentences,
- we gather the team that can deliver independently around a table to talk through the details,
- where together, virtually during the development, they determine what the final product should look like or how it should work,
- and finally, the resulting product is presented at the end of the sprint, and if everyone is happy with it, it’s ready to go live.
So documenting development and business needs is completely unnecessary if we are already verbally communicating what the expected functionality of a piece of software is. Those three complex sentences are captured in JIRA and we are ready, documentation done and everyone is happy, no resources wasted on unnecessary administration and we can move on to the next user story of the next sprint.
Daily Stand-up Meeting, the basis for effective teamwork
But perhaps agile ideas and principles could not be more misunderstood. After all, in addition to the principle quoted above, it is usually forgotten to include the very important addition, also formulated by the intellectual fathers of the agile manifesto, which reads: ‘…that is, while there is value in the items on the right, we value the items on the left more’.
So, they recognize the value and usefulness of comprehensive documentation, but they value working software more. Furthermore, opponents of documentation also tend to like to keep silent on principles that sound like:
- “Continuous attention to technical excellence and good design enhance agility.”
- “The best architectures, requirements and designs emerge from self-organizing teams.”
Wait a minute! “A good plan (…)enhances agility”? So now self-organizing agile teams also have to draw up requirements and system plans?
Well, the answer to this question is a resounding YES!
In fact, the creation of test cases, test logs or, where applicable, sequence diagrams and architecture plans should be as much a part of the life and daily routine of an agile development team as it is for a non-agile team.
MINDSPIRE Consulting offers full-scale, professional project management services to its banking and insurance clientele.
If you have any questions about agile ceremonies, contact our project management experts!
Proper preparation cannot be replaced in agile software development either
Think about it, today the IT architecture in a large enterprise environment is so complex, some parts of it so specialized, that in many cases it is physically impossible to assemble a development team that can deliver completely independently. Not to mention the fact that most development tasks require considerable mental concentration and precision.
It is hard to imagine that these developments can be done with half a dozen people around the developer while constantly giving their opinion on which command or logical operator to use in a particular line of code, for example.
For a specific business function to really take the form we want to see during the implementation phase, proper preparation is these days essential. It often happens that a given business function can be implemented in several ways, even with different approaches in the same system or with different architecture elements.
It is in the interest of a well-functioning team to assess several of these, analyze individual options properly and make a decision on the direction of implementation based on this knowledge. This is of course unthinkable without proper documentation. And not only so that the decision made by the team and the path to it can be retraced and be transparent later, but also to support change monitoring and adaptation to changing circumstances at all stages of development, which are the most important pillars of the scrum methodology.
The impact of proper documentation on the relationship between the client and the supplier
At this point, let’s go back a bit to the basic definition from which the opponents of documentation have so strongly derived their own argumentation: “We have come to value working software over comprehensive documentation.”
I wonder what the “founders” had in mind when they formulated this, why they thought it important to include it in the agile values?
In my opinion, this was done to highlight the fundamental change of mindset in the relationship between the client and the provider that they wanted to achieve by drafting the agile manifesto, namely that:
- Defining business needs should not end when the preparatory phase of a project is over, and the ink has dried on the cooperation agreement between the parties.
- Change is a value, and all must remain open to it until the final product is live.
- Projects should not be abandoned and closed in a hurry simply because something was not thought of months or years earlier when the parties were slapping hands and neither party was open to change later.
Because it’s not beneficial for anyone, neither for the client who has paid for something they can’t use in the way they want, nor for the provider who loses his reputation and motivation and has to hand over a final product even them can’t be really proud of.
All because neither party has been willing to accept that there is only one constant in life, and that is the constant change.
What are the criteria for proper documentation in agile software development?
The change that can only be defined in relation to something! This something is nothing other than the properly and sufficiently created documentation itself. The key here is adequacy and sufficiency. Because the first criterion during the preparation of development documentation is always the usability for the team, and the second is to ensure that the team operates transparently. But what exactly does this mean?
Let’s see a concrete example. According to the traditional approach, a prerequisite for IT planning and then starting development is to prepare a business specification that is as detailed as possible. Anything not included in this document will not be part of the project scope.
This document will be the alpha and omega of the development project, and for any issues that arise later in the design or implementation phase of the project, the parties will refer back to it to decide on the basis of the “bugfix or change request” question that will arise again and again.
Documents prepared along these lines bear the following error marks:
- They are too voluminous, try to cover all details and typically focus more on the “how” than the “what”, the “who” and the “why”.
- They tend to take too long to prepare, go through too many iterations and often become obsolete and outdated by the time they are finalized.
- They contain too many constraints, so they do not allow sufficient room for creativity at the design and implementation stages. In other words, even if the IT designer or developer comes up with a better, more efficient, modern proposal for implementation, it is not or cannot be implemented because it is “the business need doesn’t contain that”.
In contrast, according to the agile approach, the minimum requirement for the business need, i.e. the user story, is to answer the three basic questions “what”, “for whom” and “for what purpose”.
In this case, the aim is not to define and circumscribe the legal and structural relationship between the provider and the client, but rather to formulate a basic requirement that focuses on the end user. It doesn’t have to be perfect and complete, it doesn’t have to capture all possible scenarios, it is sufficient to describe the basics, as the rest will be added by the agile team itself during design, refinement, development and testing.
This approach is great because the documentation produced does not hinder creativity and continuous improvement, but supports it. It is not produced for its own sake, but organically follows the realization of a business need, an idea, from its inception to its implementation.
Summary
In our view, therefore, agile methodology does not mean the complete absence of documentation, but rather its adequate and targeted preparation to support the development process.
The agile principles emphasize that while working software is preferable, comprehensive documentation has value and well-prepared documentation promotes transparency in the development process, supports the tracking and implementation of changes and contributes to team’s effective work.
In a large enterprise environment, documentation is particularly important, as the complexity of the IT architecture requires precise preparation and documentation of decisions.
MINDSPIRE Consulting has significant theoretical knowledge and practical experience in agile project management in the banking and insurance industries.
If you have any questions about this article or agile project management, please contact our experts!
Author
Gergely Gyenes
Agile project management supervisor
Gergely has more than 20 years of experience in the field of retail loans.
He is equally experienced in planning business and IT processes, as well as in project management, test coordination and data analysis.
He is committed to teamwork, constantly supports and encourages his colleagues to achieve the best possible performance.
In the past four years, he worked as an agile product owner on several residential loan projects, and also participated in the agile transformation of organizations and projects.
Please see MINDSPIRE’s related:
Project Management
Services
Project Management
Office
Do you have a question or comment about this post?
Send us your message and our experts will contact you!
Our latest Banking and Insurance Project Management Office References
Are you interested in our banking and insurance PMO services?
You can find more information here:
Our latest Banking and Insurance Project Management References
Would you like to know more about our banking and insurance project management services?
You can find more information here: