The documentation dilemma
The documentation dilemma in agile projects: why it happens and how we can fix it
5 minute read
So what’s the deal?
In the fast-paced world of agile project management, flexibility and adaptability are key. However, one significant issue that often arises is the neglect of proper documentation. While agile methodologies emphasise working directly in software over comprehensive documentation, this doesn’t mean documentation is unnecessary.
In fact, the lack of documentation can lead to numerous problems, from miscommunication to reduced accountability. This article explores why this issue is prevalent in agile environments and offers practical solutions to ensure teams strike the right balance.
The problem.
Agile methodologies focus on iterative development, frequent feedback, and adapting to change. From my experience paratrooping into companies to troubleshoot project and workflow problems, teams often misinterpret these principles to mean that documentation is obsolete, or that they “don’t have the time” to take suitable notes. When this culture develops, it can result in critical decisions being made verbally without any written record, leading to confusion, lost knowledge, duplication of effort and errors down the line.
This can manifest itself when key decisions about a feature are made during a sprint planning meeting but never documented. Afterwards, team members have different recollections of the decision, causing significant delays and rework. In other instances, the lack of initial requirements documentation leads to a misunderstanding about the product or project scope and functionality, and this can result in scope creep, stress or tension between teams and stakeholders, project delays and associated budgetary problems, or products that don’t meet the client’s expectations.
Possible causes.
Several factors can contribute to this documentation dilemma.
First, there is often a misinterpretation of agile principles, with teams believing that agile eliminates the need for documentation. Agile is NOT a methodology, it’s a philosophy. It is applied differently in every business I have worked with, with varying results depending on the culture within the agile teams and the application of the philosophy with appropriate methodoligies and processes.
Second, cultural factors within a company may prioritise speed over thoroughness, leading to inadequate documentation practices. This is particularly prevalent in startups that want to move fast to show results, but this can often lead to problems later down the line when they need to scale because the documentation is just not there, or (worse) it’s a complete mess. Additionally, many teams lack proper training on how to balance agile practices with necessary documentation, and, as a result, there are no processes or workflows to allow them to produce the documentation in a consistent way.
Finally, there is a perception that documentation is redundant or unnecessary in a fast-paced environment, which can discourage or even pressure teams to ignore proper record keeping to pursue 'more critical' tasks.
Issues arising from a lack of documentation.
Miscommunication.
The absence of documentation can lead to various issues. Miscommunication is a significant problem, as verbal agreements can easily be misunderstood or forgotten. This can result in inconsistent implementation and project delays.
Loss of knowledge.
Furthermore, there is a risk of losing critical knowledge when team members are sick, leave the project or company, or even during planned absences and vacations. Without written records, valuable insights and decisions may be lost. Lack of documentation also reduces accountability, as there is no written record of decisions or assigned tasks.
Poor salary investment.
Onboarding new team members becomes particularly challenging without proper documentation. In companies with a flat hierarchy, understanding roles and responsibilities is crucial. When documentation is lacking, it’s unclear who to approach in the absence of key team members. For example, if a health and safety officer is off sick, it’s uncertain who is responsible for their duties.
Again, in a very real scenario, I have encountered CEOs and senior executives in smaller businesses and startups needing to spend time to onboard new staff. This is hardly an ideal salary investment, especially when the new team members are in junior management, on the coal face or even working students and interns. A senior executive should be focused on strategic initiatives, not repetitive onboarding tasks.
Well-structured documentation would allow new recruits to independently access information and complete training, especially important in tech startups where founders and executives are focused on rapid growth.
Solutions.
To address these issues, it’s crucial to implement effective documentation practices in agile environments. Training and coaching can play a significant role in this. Teams should know the value of documentation and how to integrate it into their agile workflows. Workshops or coaching sessions with a strong emphasis on continued feedback and adaptation would bring focus to the relationship between agile practices in projects and delivering concise and necessary documentation.
Implementing workflows that support structured documentation is also essential. This involves developing a process for creating lightweight documentation that is sufficient to keep the project on track without being overly burdensome. Providing templates and examples of effective agile documentation can help teams understand how to document efficiently, as well as utilising inexpensive technology to rapidly produce the required documentation.
Rituals such as daily stand-ups, sprint reviews, and retrospectives should include brief note-taking to capture key updates and decisions. Daily stand-ups often throw up issues that will require a change or course correction. Documenting these important updates is exceptionally important in terms of knowing what has happened and why, and it may form the basis for informing or negotiating project deadlines with stakeholders. Likewise, sprint reviews should be used to record feedback and decisions, and retrospectives should maintain records of issues discussed and agreed upon action points. This does not need to be a cumbersome task, it just needs a well thought out workflow and someone responsible for maintaining the quality of the documentation.
Finally, we can incorporate digital tools and technologies to facilitate easy and consistent documentation. Tools like Confluence for wiki-style documentation, JIRA for tracking decisions and tasks, and collaboration tools like Slack can help maintain written records of conversations and decisions - but - and this is a big but, we should ALWAYS maintain a single source of truth. Decisions made in Slack should not remain there, they should be added to Confluence (or wherever you keep your official documentation). It's also important to recognise that we need to establish best practice in these tools and nominate someone to be responsible for quality management. Again, it's important to recognise that we need to establish best practice in these tools and nominate someone to be responsible for quality management.
Conclusion.
Embracing documentation as a tool is crucial for enhancing communication, accountability, and consistent project success. Agile doesn’t mean abandoning documentation but adapting it to fit a more dynamic, iterative workflow.
While agile methodologies emphasise flexibility and adaptability, proper documentation remains essential for project success. By training teams, implementing structured documentation practices, and incorporating the use of appropriate tools, teams can strike the right balance between agile practices and producing the necessary documentation.
Struggling with documentation?
We can help! At BRAW, we specialise in optimising processes and workflows to ensure your team strikes the right balance between agility and thorough documentation. Reach out to us today to learn how we can support your project success.
Smoother projects, simpler reporting and delivery on time. Let’s BRAW help you work with greater efficiently and improved productivity.
