Creating “Customer Focused” Documents in an Agile Environment

By Tony Xavier

Agile is a popular development method primarily used by software companies. In the Agile method, teams strive to deliver a fully functioning, high quality, and potentially shippable product increment at the end of each Sprint. As a result, Documentation becomes an essential part of the Sprint deliverable in order to meet Stakeholder Requirement.

The primary focus of Agile development is to deliver the right products with high quality. Hence, there is need for Technical Communicators to create high quality Customer Focused Documentation. However, the combination of Agile’s high speed of development, short delivery cycles, and limited requirements documentation presents a unique set of challenges in creating customer-focused documentation.

The Challenges…

• Dynamic Requirements: The requirements tend to change because of changes in priorities, bugs in the product, etc. Changes in requirements results in rework and extra documentation effort.
• User-Story Vs Features:  Most often the Agile User-Story format is not detailed enough to provide all the information about a feature, as the Development Process is iterative. This means that the feature enhancements and functionality are stabilised much later in the release. This results in rework in the documents.
• Distributed Teams: This has a huge impact on communication and getting technical inputs from the engineering team. Writers have to send several emails and spend extra time over the phone to gather inputs and gain understanding of the feature. This additional waiting time impacts the timeline, productivity, and quality of the documentation.
• Tech Writer Multi-tasking: The greatest challenge for the Writer is to balance the workload and handle context-shifting. As a result, the Writer ends up working on multiple features; and juggling different user stories. The Writer is also forced to estimate bandwidth based on time allocated to each team rather than on the varying amounts of content required. This affects the sprint planning and leads to poor quality documentation.
• Doc Estimation Vs Team Estimation: Most often documentation is included as a part of the Definition of Done (DoD) of a User-Story and does not get absolute time units. Hence, Writers are unable to give enough weight to the documentation effort and the documentation estimates are not included in the teams estimates.
• Sprint Reviews Vs Doc Reviews: A Sprint Review covers only the features and Documentation is ignored or given a lower priority. Most often the Reviewers are the Developer and Testers. Who are extremely busy on Engineering the product. As a result, they give documentation a cursory glance and declare it “okay” with no or very little helpful comments. Others fail to follow the steps as listed in the documentation when testing procedures, and have no way to ensure the writer captured everything accurately. As a result, the documentation reviews are moved towards the end of the release.

Tips for Success…

• Tech Writer Involved Early: If your Tech Writer finds that User Interface or feature difficult/confusing, so will users. Having the Tech Writers involved during the Sprint can also help the Quality Assurance team discover problems. Early participation of the documentation team in sprints also allows Writers to accurately assess the amount of total effort that the project is going to take. This helps the Writers in release planning of the documentation.
• Expert knowledge of the product: Expert knowledge of the product helps you to write accurately and effectively, with minimal supervision. Get access to the product/software build, ask questions, and gain your own understanding of how the product works. This ensures that you are not always dependent on the Developers and Quality Assurance Engineers to collect information. If you demonstrate a solid understanding of the product, the team trusts you more when you point out a technical or usability problem and make a suggestion for change.
• Delay the Documentation: Delaying the delivery of user documentation by one sprint cycle reduces both the cost and the risk associated with documentation. Cost is reduced because you won’t waste time documenting information that changes. Risk is reduced because there is less chance that your existing documentation is of date.
• Key stroking content for Technical Accuracy: Test the procedures, examples, and instructions documented on the actual software build to ensure accuracy. Essentially, this allows you to place yourself in the shoes of the user and to create documentation that does not assume that the user can figure out information and procedures you have failed to include. This process helps you identify any missing steps and errors that could have been overlooked in the earlier doc reviews.
• Live Documentation Reviews: To avoid the last minute rush, try getting engineers, stakeholders, and customers focused review of the document. Ensure that the time for live documentation review is scoped in the sprint planning. It is mandatory to receive Management Support for having successful doc reviews.
• Direct customer feedback: The Agile methodology allows you to attend Sprint Demos, Product Demos, and other customer-facing meetings. This provides an opportunity for you to receive direct regular feedback and thereby improve the quality of the final documentation.

Concluding Thoughts…

Technical Communication in an Agile environment can be a very challenging task. It can take several takes to get it right. All in all, Effective Communication and Active Participation (of the Tech Writer within the Agile Team) can help overcome this barrier. This will add value both to the Agile Team as well as the Product.

Tony Xavier is a Lead Technical Writer with Innovatia India. He leads the Cisco Customer Care Business documentation team. He has worked extensively in Agile framework and has a good understanding of Agile principles, practices, tools and techniques.