Since the introduction of the Agile Manifesto, software development has changed its trajectory. Moving from waterfall design to an agile way of building software provided greater business agility to listen and respond to evolving customer needs.
Agile software development laid a solid foundation for technical documentation to change the way technical documentation is produced. One of the core principles in the Agile manifesto is “Working software over comprehensive documentation”. This principle emphasizes two things for technical writers:
- Stronger collaboration with the developers’ team to build documentation in line with the software development lifecycle
- Produce a minimum viable documentation that is good enough so that your customers can use that documentation right away
In this, both software developers and technical writers are aligned to respond to change quickly rather than following a fixed plan. This sets the precedence for technical documentation team organisational structure change, documentation processes, and frameworks that adopt agile principles. Welcome to “Agile Documentation”, a newer way of building software/product documentation that offers business agility and competitive advantage.
What is Agile Documentation?
Agile is a lightweight framework that helps people, teams, and organizations generate value through adaptive solutions for complex problems. Agile documentation refers to the practice of producing documentation following the principles setup in the Agile manifesto. Technical writers work closely with software developers to prepare product documentation at a pace aligned with the developers with sprints.
The technical documentation adapts agile ceremonies including standups, sprint planning, and retrospective. All the learnings are shared amongst the product owner, and product managers. Adapting the principles of the agile manifesto inside the product documentation team supplements product features and provides a complete product experience
Importance of documentation in Agile software development
The Agile manifesto lays out fundamental principles of the agile software development process such as
- Individuals and interactions over processes and tools
- Working software over comprehensive documentation
- Customer collaboration over contract negotiation
- Responding to change by following a plan
However, this manifesto leaves the implementation open thus a lot of people have different approaches at the beginning of the agile software movement. A lot of convergence and best practices emerged after a few years of many companies experimenting and implementing with agile ways of software development. Customer focus is the central theme of agile manifesto as software is a solution to a customer business problem.
Agile methodology provides relentless focus on customer business requirements and ensures that a Minimum Viable Product is built as a solution. In supporting the agile software solution, documentation should be accompanied by every software release. The importance of agile documentation in the agile software release cycle can be summarized as follows
- Software and documentation shall be released simultaneously to maximize customer experience
- Agile documentation processes to supplement software developers providing business agility
- The documentation team and software developers adopting the same agile methodology and processes helps to get consistent practices across the team
- Agile documentation processes set the stage for tighter collaboration with software developers
- Agile documentation also helps with reducing time to value for customers to utilize the software solution holistically with accurate documentation
- Communicate technical information to your customers such that the product value can be maximized
- Compliance / regulatory bodies mandate to have technical documentation as part of their software product
3 Questions to ask while Creating Agile documentation
Creating documentation utilizing agile methodology is an art that can be mastered over a period. There are three important questions you need to ask while creating an agile documentation
1. What documentation to produce?
Figuring out “what” is the preliminary task for a documentation team as the product owner usually communicates “why” to the documentation team and software developers. Experienced agile documentation team usually have a framework for “what” as it depends on what purposes do the documentation serve and what it needs to encapsulate. The famous “what framework” in the agile documentation is Diataxis.
Diátaxis framework in the agile documentation approach provides a holistic understanding of the needs of documentation users in their cycle of interaction with a software product. Diátaxis framework in the agile documentation lifecycle is easy to apply.
The main questions you need to ask in understanding the “what” in agile documentation are
What documentation will be required before the project begins?
Diátaxis framework helps to answer this question as the type of documentation depends on the purpose it is going to serve. The tutorials, How-to guides, reference materials, and technical explanation requires a different style of writing for their intended audience. This is figured out before the sprint begins
What kind of documentation will be required during the project?
During the agile sprint, the scope of the software development might shift as the customer requirements are still evolving. During the sprint, the documentation team might need to change the documentation that is being produced. Depending upon the scope change or minor amendments to the sprint scope, the type of documentation varies
What kind of documentation will be required once the product has been deployed and implemented?
If the scope of the agile sprint has not been changed, then the final documentation will not see a change since what has been planned will be delivered. However, if the scope of the sprint has changed, then the final documentation after software deployment may look different. In this case, a continuous improvement process is integral to agile documentation
2. Where to keep documentation?
Documentation workflow plays an essential role in ensuring that documentation is produced that meets the customer’s expectation with acceptable quality and high technical accuracy. The documentation should be accessible by all stakeholders especially customers after the release of a particular product feature at the end of each sprint.
Accessible documentation location
The documentation can be drafted using any SaaS-based knowledge base solution that aligns with agile documentation methodology. The common location for agile documentation is a knowledge base site / documentation site where all product-related documentation is published. The customers are aware of this location as internal links inside a software product usually point to this location. Sometimes, the in-app help also shows where the product documentation resides
Documentation repository
It is also beneficial to retain accessible documentation in a repository that can be updated frequently if agile documentation is using Git like system to build the documentation. In this case, the documentation site is generated using static site generator platforms such as Jekyll or Hugo
3. When to choose the agile approach?
Agile documentation works best if the documentation should be produced simultaneously with the software development. This can be related to the just-in-time techniques in the manufacturing domain. Most of the software development happens in an agile setting thus agile documentation is applicable to most of the software development. Agile documentation is not apt for
- Software development which uses the traditional waterfall model of software development
- Software teams that works independently and may not be customer driven
- There is no need to release product documentation as part of the release cycle
Critical elements to include in Agile Documentation
A light-weight one page project documentation can be part of agile documentation process. The below list gives you an overview of critical elements that needs to be covered in agile documentation. They are
Project scope
A short description detailing what needs to be covered in the technical documentation such that it meets the expectation of the customer. Thus, the documentation should be concise, precise, and technically accurate.
Specification document
If the software feature is meant for a highly technical audience, a technical specification document can be useful that covers technical specification/requirements
Compliance conditions
If any compliance conditions need to be met by the documentation, it can be detailed out. This is applicable to medical products, manufacturing, oil and gas industries
Production support documents
If the software product is released in different stages, then the documentation should be released for different product environments and system settings. This includes releasing different documentation for different product versions and different product stages such as alpha, beta, and GA
Guides for end- Users
If addition to technical documentation, there might be a need for producing technical guides for any partners/ resellers on configuring technical aspects of the product. This documentation might be not shared with end-users
Training Manuals
Based on the project scope, training manuals can also be released to bolster the impact of software documentation
An intuitive technical documentation software to easily add your content and integrate it with any application. Give Document360 a try!
GET STARTED
How to do Technical Documentation in Agile
The steps involved in producing technical documentation are detailed below
Plan your agile documentation
Planning for your agile sprint is the first step in agile documentation. The product owner and project managers usually set the objectives/goals of the agile sprint. This helps to understand the scope of the work for agile documentation. The user stories are drafted during the sprint planning meeting and a responsible person is assigned for each user story. The documentation team does the task breakdown during the sprint planning
Update activities during daily stand-ups
Developers and other agile members can contribute to documentation effort during the sprint. This accelerates documentation development. During daily stand-ups, each documentation team member will update their tasks. A scrum master would orchestra the task management and prioritizing tasks based on dependencies.
Showcase your documentation artifacts
During the showcase event, the documentation can showcase the documentation they have built and it is shared amongst the stakeholders
Take part in an agile documentation retrospective
Attend the sprint retrospective to share things on “What worked well”, “What we need to improvise” and “What we need to stop doing”. A scrum master usually documents these things and sets a stage for continual process improvements.
Product backlog
A clear product backlog that helps documentation priotizes efforts and time to align with the product roadmap. This helps to do some strategic planning rather than managing tactical plans
Also Read: Agile SaaS Documentation: 5 Key Principles to Supercharge Your Product Documentation
Best practices in writing Agile Documentation
Best practices are still emerging in drafting agile documentation as many technical writers are adapting the agile processes in their documentation effort. Some of the best practices are summarized below
- Include only minimal and relevant information
- Recognize users and document specific goals
- Take a test-based approach to define requirements
- Avoid building comprehensive information (keep it simple)
- Nest your articles(tree-view)
- Be sure to articulate things clearly
- All artifacts are sourced from single source
- Customers are aware of finding documentation via search engine
- Collaborate with a wide range of stakeholders
Also Read: What is IT Documentation: Types, Examples & Templates
Wrapping Out
Agile documentation provides a plethora of opportunities for the documentation team to focus on customer’s business requirements and helps to maximize the product experience. Agile documentation can take in a lot of cues from the Agile manifesto and adopt most of the agile practices into their data-to-day activities. Adopting best practices of agile documentation helps to nurture documentation culture amongst the software team thus fuelling product lead growth. Agile documentation also helps to seamless product experience whereby product and documentation are considered as one rather than separate entities.
Also Read: Create Killer SaaS Product Documentation for Your Customers
Try Document360 right away if you’re prepared to test the writing tools for creating your agile documentation. Document360 compiles and organises all of your team’s documentation, expertise, and project requirements in one place. Create a shared knowledge base for your team so they have access to documents and data. Prepare your team to work in an agile environment with accurate documentation in real time to save time and prevent mistakes.
Interested in Document360 Knowledge base? Schedule a demo with one of our experts
Book A Demo
–