Category: Technical Documentation
Last updated on Aug 8, 2023
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:
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.
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
The agile manifesto lays out fundamental principles of the agile software development process such as
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 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 provided 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 with every software release. The importance of agile documentation in the agile software release cycle can be summarised as follows
Also, Check out our article on Documentation Culture
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.
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
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
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
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
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.
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
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
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
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
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.
If the software feature is meant for a highly technical audience, a technical specification document can be useful that covers technical specification/requirements
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
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
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
An intuitive technical documentation software to easily add your content and integrate it with any application. Give Document360 a try!GET STARTED
The steps involved in producing technical documentation are detailed below
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
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.
During the showcase event, the documentation can showcase the documentation they have built and it is shared amongst the stakeholders
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
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
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
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.
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 expertsBook A Demo