The Waterfall model is characterised by a number of documents, artefacts, and procedures that are essential to its successful implementation. However, adopting principles from Lean and Agile methodologies suggests that the amount of paperwork should be reduced in order to streamline the development cycle. Consequently, it is important to identify and prioritise paperwork that is necessary for the project and eliminate any redundant or unnecessary paperwork.
Project managers are often able to understand how the linear process of Waterfall stages can be adapted to the more iterative structure of sprints, as the same objectives still need to be accomplished with this change in structure. However, the removal of documentation associated with Waterfall can be a more difficult adjustment to make, as it entails a complete shift in approach. This means giving up control of certain elements of the process, tolerating an element of unpredictability, and granting the delivery team more autonomy in making decisions as they go.
The Status Quo Of The Traditional Documentation Approach Is Being Challenged
The Waterfall methodology is renowned for its focus on defining project requirements and creating solutions. While this approach can be effective when the requirements are explicit and unlikely to change, in reality, this is rarely the case. Over the past few decades, many companies have found that the ever-increasing rate of change often results in the client’s requirements having altered significantly by the time the documentation phase is completed.
Agile methodology emphasises the importance of delivering results and providing value to stakeholders. It is designed to prioritise tasks that directly contribute to the customer’s satisfaction, while discouraging peripheral activities that do not have a direct, immediate impact on the customer experience.
Waterfall versus Agile documentation
Organisations often have varied levels of documentation, which may differ depending on the project. As an example, here are some of the common documentation practices for both Waterfall and Agile projects:
The Case for Documentation
Waterfall methodology encourages an organised and comprehensive approach to creating documentation, which may appear to be overly meticulous. However, prior to deciding that such an approach is an unnecessary effort, it is important to consider the potential benefits of having a well-developed system of documentation.
The ability to think strategically
It is often said that those who do not plan are planning to fail, and this is certainly true in project management. Documentation is essential for project managers, as it allows them to take the time to properly consider each decision and arrive at the best solution. There is a common misconception that Agile values functioning software above extensive documentation, leading some to rush into the market without proper planning. This strategy, known as “throwing something against the wall and seeing what sticks,” can be incredibly wasteful and time consuming. By taking the time to design solutions, create strategies, and deliberate actions, project managers can save time and resources in the long run.
UX and Functional Consistency
As organisations expand from a small number of founders to larger numbers of people, multiple teams may be working on similar or related products. However, it is important to recognise that, from the perspective of the consumer, all of these elements are part of the same product. To ensure that the user experience is seamless and consistent, it is essential to have clear documentation outlining the functional and user experience levels, rather than allowing cross-functional teams to operate independently from one another. This will ensure that there is a coherent user flow.
Documentation Can Be Used to Create User Guides
Waterfall dedicates a significant amount of time to outlining solutions and the methodology used to implement them. Furthermore, front-end developers are provided with high-precision design images which, in turn, reduce the amount of effort required to create user manuals for both internal and external use, as opposed to building them from scratch.
Documentation is unnecessary in Agile development environments
It is widely acknowledged that employee turnover can be a major factor in the need to mandate documentation. Managers are concerned that when employees leave, their institutional knowledge will be lost and new employees will need to be hired to fill their role. This raises the question of how the new employees will be able to understand what has been established and how it works. Additionally, it will take the new employees time to become acquainted with the system, and the current team may not have the time or resources to provide adequate mentorship to the new team members.
It is anticipated that robust documentation will expedite the onboarding process of new staff members, who will be able to largely work autonomously. Nonetheless, Agile methodology further reduces the need for documentation by utilising interactive tools, thereby shortening the duration of onboarding. The following are several instances of how Agile methodology lessens the need for documentation.
Regular Interaction Between Product Teams and Agile Team Members
The Agile Manifesto emphasises the importance of individuals and relationships over procedures and technologies. This is because the requirements of a project can vary during its course, and new ideas can arise which necessitate a reassessment of said requirements. Agile methodology therefore encourages direct communication with the source of the requirements, rather than relying solely on written documents which may become outdated and need constant updates.
Grooming and Planning are Separate
Regularly collaborating on backlog grooming and sprint planning activities helps to break the larger project into smaller, manageable pieces. This makes it easier for new team members to understand their individual responsibilities and begin making meaningful contributions to the project from the start, even if they don’t have a comprehensive understanding of the overall project.
Using User Stories for Documentation Helps
User stories provide a straightforward structure for project managers to capture the essential requirements of a project, helping to ensure that all team members have a shared understanding. Even if a user story is not included in a sprint, the time taken to draught it is minimal, making it a highly efficient way of producing documentation. As the user story progresses through sprints, it can be augmented with additional details such as wireframes, designs, and acceptance criteria. This allows the documentation to be tailored to the relevant development phase, making it highly disposable.
No more code documentation is required
Pair programming and code review provide ongoing opportunities to share technical knowledge among the team, particularly with new members. By providing continual feedback, the team can create and maintain an up-to-date, dynamic set of shared knowledge that is applicable to various circumstances and not just stored away in a document.
Agile Ceremonies
Regularly scheduled stand-up meetings, sprint reviews, and retrospectives provide a great platform for team members to address problems and make decisions efficiently without having to resort to emails or paperwork. The limited time frame for each of these ceremonies ensures that only the most necessary information is discussed, thus eliminating any superfluous discussion that would be a waste of time.
By implementing the aforementioned strategies, paperwork can be reduced and project objectives can be given precedence, ensuring that no information is lost due to inadequate documentation.
Documentation methodologies that combine both hybrid and non-hybrid documentation
Despite the fact that Agile methodology is designed to be flexible and adaptive, some organisations still prefer to maintain certain types of documentation. This is due to the fact that each project is unique and requires specific considerations to be taken into account. The Agile approach does not provide a set of rules or regulations that must be followed, allowing for a more customised solution to be implemented.
There are certain situations where Agile may be used alongside with more time-consuming documentation approaches.
Bringing UML and Agile together
It is recommended to adopt a standard modelling language, such as Unified Modelling Language (UML), to create a depiction of a system. UML is well-structured, and keeps information concise and focused on the necessary components, while minimising the use of written language. To facilitate the modelling process, tools like StarUML and Draw.io are available.
Code documentation generators
An alternative to making the code more understandable is to augment it with organised and descriptive comments. These comments can provide information about the class details, method details, argument use, dependencies, and other relevant areas. Additionally, there are several documentation generators available that can be used to automatically create user-friendly documents from source code. These programs may be tailored to a specific programming language or may be general-purpose.
Design and User Experience Documents
Wireframing and user experience (UX) tools can be incredibly useful when defining requirements for a project. Creating wireframes, mockups, user flow diagrams, sequence diagrams and other visual aids can help to make the project process simpler and make it clearer for the technical team to understand what needs to be built. Additionally, design papers can be an effective way to provide more specific documentation. There are a variety of wireframing and UX tools available to choose from.
Project management tools document automatically
The utilisation of more sophisticated project management tools, such as JIRA, Confluence, Asana, and Basecamp, can provide an excellent opportunity to streamline all project-related information into one centralised location. These tools can effectively link, label, and assign tasks to team members who are able to provide feedback and report any difficulties. By leveraging these tools, organisations may be able to generate a substantial amount of documentation with minimal effort.
In addition, it is commonplace for a component of the documentation requirements to arise from reporting obligations. Stakeholders need to be informed of team performance and other relevant metrics. By utilising project management software, it is easy to create custom dashboards and visualisations that accurately depict project progress and connect to relevant material inside the product.
Document Management Requires Balance
The authors of the Agile Manifesto place emphasis on delivering functioning software over detailed documentation. They acknowledge, however, that there is still value in the latter. Therefore, Agile does not suggest forgoing all documentation; rather, it encourages a balance between developing functional software and documenting the project as necessary, without significantly impeding the development process.
Project managers must carefully consider the amount of time to be allocated to documentation and the actual delivery of functional software, as well as accurately determine the places where documentation is necessary for long-term success. This requires a delicate balance in order to ensure that projects are completed with minimal delays and to the highest standard of quality possible.
