Developing User Documentation in Agile- Myth or Reality?
In last few months, I met a lot of people with whom I had discussion regarding the development of user documentation in Agile methodology. Most of them had this myth that agile does not require any documentation. Whenever we discussed about documentation, they told me, Oh! in agile what tech writers will do; agile does not require any documentation I debated that documentation is important software deliverable and tech writers can contribute significantly to this. But they were never convinced with this argument.
Through this post I would like to share my experience and role of Tech writers in Agile teams.
User documentation is one of the important deliverable of a product and same is true in Agile environment. However, documentation requirements are driven by client for service based organization and for product companies user documentation is always integrated with the product. In Agile, documentation development may fall under two categories as mentioned below:
- Process Documentation: Project plans, Test plans, Minutes of meeting
- Product Documentation:
System documents: Functional specifications, Design documents, Architecture diagrams, Source code documentation
User Documentation: User Manual, Installation Guide, Online Help, and Quick Reference Guide, Release Notes. These documents are integrated with the product and bundled with the code to the client site. Without these documents the end deliverable is considered as incomplete.
These are not standard set of documents; they are prepared based on client or team's requirement and setup.
How Tech writers operate in Agile Environment
Tech writer's working style has changed in Agile if we compare it with waterfall methodology. Few years back when I moved to this new setup of Agile, many questions came to my mind: How I am going to operate in the Agile mode? How I will document features which will be developed in Sprints?
Gradually when I started working with the team, I realized that Tech writers also follow the same process as the developers and testers. Though the timelines are tight in Agile, writers also simultaneously document features as they are developed in order to be in sync with process timelines.
Writers are a part of project team and are involved from initial phase of discussions. They are a part of daily standups, planning meetings, and retrospectives.
Documentation tasks are also treated like any other requirement of the project. User stories are created for documentation tasks also. The content is developed by translating user stories into task oriented topics. The tasks are added to the backlog. The planning session also includes the estimates for documentation tasks. A user story is created for the quality assurance team to review the documents/online help. If they cannot accommodate it in sprint cycle, then request is raised to review the documents in hardening cycle.
As in agile the changes are frequent, documentation gradually evolves from sprint to sprint or release after release to keep track of changes made.
Right Documentation at Right Time
As timelines are tight in agile mode, so Tech writers always have to be on their toes in order to get the information and document them on time. One of the important aspect of Agile is documenting the right information at right time. Like traditional methods, documents are not developed at the end of the project. In agile; documents are developed in parallel with the product feature development. As the developed features evolve documentation also changes so that it is in sync with the product. In order to deliver documents on time, here are some of the changes that we implemented to the content development process to prepare stable and quality documents within the tight timelines of sprint cycle. The below changes worked & proved successful amongst our user base:
- In User Manual we used to put description of all the screen elements. Later we modified this approach and screen elements which are self- explanatory and intuitive enough are not included in the Manuals.
- Another change which we implemented was that, before starting the content development; our team took feedback from the client on their documentation requirements. So mainly we followed reactive content writing approach and documented the features which are required by the end user.
To summarize, user documentation is an important part of software deliverable. Without end user documentation the software package is incomplete. In Agile, documentation is treated like any other project requirement. The documentation tasks are estimated, prioritized like other user stories of the project. In agile, user documentation has evolved and internal documentation has moved towards minimal or comprehensive approach.