Agile Best Practices for Technical Writers

By Bonnie Demback | Senior Member

I am a senior technical writer at Sparta Systems, Inc. and document Sparta’s flagship Enterprise Quality Management System (EQMS) product, TrackWise™. I have spent most of my 20 years’ experience as a technical writer in a Waterfall development environment, and the big challenge for me has been to get accustomed to the Agile methodology that is in place at Sparta. To change my mindset, I began researching the Agile methodology and best practices. By embracing best practices for technical writing that have been proven effective for other writers using the Agile methodology, I have been able to be adapt to this new methodology.

Waterfall vs. Agile

Waterfall software development is a linear, sequential approach to software development. Each step represents a distinct stage of software development, and each stage generally finishes before the next one can begin. Typically user documentation cannot be started until testing has begun at the very end of the cycle.

Agile is “a group of software development methods in which requirements and solutions evolve through collaboration between self-organizing, cross-functional teams. It promotes adaptive planning, evolutionary development, early delivery, continuous improvement and encourages rapid and flexible response to change” (http://en.wikipedia.org/wiki/Agile_software_development).

As Lee Turner aptly states, “Agile development is an ever-changing, turbulent environment that may cause you to wonder if you even have time to plan.” Unlike what is expected in Waterfall approaches, Ester Gonçalves postulates that, in Agile, “as features are being added incrementally, the documentation should be incrementally produced as well, evolving along with the development of the product.”

A Writer’s Guide to Surviving Agile Software Development states that “writers are trying to figure out how to meet deadlines, write quality documentation, and stay sane as their software companies switch from the traditional Waterfall method of development to the increasingly popular Agile methodology.” Agile development for a traditional Waterfall technical writing team looks like chaos. My first thought was, “What’s going on?”

The Manifesto for Agile Software Development clearly states that value is placed on “working software over comprehensive documentation” and “responding to change over following a plan.” While these tenants are important to Agile, it does not imply that there is inadequate documentation or no planning. I have found just the opposite to be true. The “comprehensive documentation” referred to in the Manifesto relates to phone book sized requirements and upfront design documents that are usually out-of-date by the end of the Waterfall development cycle.

With Agile in place at Sparta, my approach to writing technical documentation had to change. Agile values documentation as a part of the product, feature, or enhancement being delivered to customers, and the new challenge for Sparta’s technical writers is writing and delivering documentation as features or parts of features are developed during two-week sprints. Technical writing teams need to adjust their processes and documentation delivery methods, and employ known best practices to successfully adapt to the different methodology.

The best practices that follow reflect process changes that Sparta’s documentation team needed to embrace as their new approach to Agile documentation development.

Setting Expectations – Documentation as a Requirement

The content of a software release may change based on changes in business priorities. We need to keep in mind that our documentation, just like our code, can be deferred or adjusted iteratively at any point during the project, should the product owner decide that the project needs to go in another direction.

In Writing End-user Documentation in an Agile Development Environment, Tana Berry asserts that “the investment in documentation is a business decision, not a technical one. You shouldn’t create documentation because your process says you should but instead because your stakeholders say you should.” According to Gonzales’s A Roadmap to Agile Documentation, Agile “does not defend in its base principles the option of having no documentation at all. But it reminds teams that the focus should always be on delivering value to the customer. In the process of producing documentation, this key principle must also be taken into account.”

In an Agile approach, documentation must be considered just another component of the product that is continuously updated during iterations throughout the development lifecycle. Product management (PM) and business analysts (BAs) need to rethink how documentation is presented to our customers and take an active role in:

1. Defining the expectations and requirements for documentation deliverables.
2. Verifying what is needed and what can be ignored based on customer needs.

At Sparta, we have implemented “Doc Epics” to capture requests for documentation (as suggested by Jean-Luc Mazet in Agile Technical Documentation), since at least some of the documentation will take more than one sprint to complete. Content is chunked into Doc Epics and Doc Issues in our Agile process. Documentation tasks are defined in each sprint. We develop content in correlation with the user stories developed and tested sprint-by-sprint.

It is important to stress with the scrum teams that these requests should be submitted as early in the process as possible. Development teams do not know how many sprints the project is going to last. This is a reason Mazet stresses: “the early participation of the documentation team in sprints to be able to fully and accurately assess the amount of total effort that the project is going to take, including user documentation and online help.”

Technical writers need to involve the scrum team(s) to accomplish their tasks. Sprint-by-sprint content development is part of completing the sprint. Technical writers and scrum team members have the same goal—to deliver working software and that includes user documentation. Therefore, the team needs to ensure that documentation tasks (information gathering sessions and reviews) are properly defined for each sprint. This way SMEs and team members will be aware that time will be devoted to customer-facing documentation during the sprint or the following sprint. It also provides a heads up to all reviewers and approvers. Time needs to be allotted for the documentation tasks.

Best Practices for Technical Writers

I have identified the following best practices that our Agile documentation team needs to adopt.

1. Adapt to Change and Remain Flexible

   Priorities can change rapidly in any organization. The need to quickly respond to customers’ evolving needs causes changes in the prioritization of development work. Development work scheduled for certain sprints during planning can be moved to a lower priority based on higher priority items being introduced at any time. With Agile, documentation development needs to be reactive as priorities change.

   The idiom “the best laid plans of mice and men often go awry” can be applied to the reality of an Agile development process. The Agile environment has change as its foundation. No matter how well we plan, we should always be prepared for change. Change is an expected part of the Agile process, but remember change does not imply chaos. It needs to become an accepted part of the process.

   The bottom line for technical writers (and all Agile team members) is that we need to:

   • Be flexible and respond to change
   • Be prepared to redirect our efforts accordingly
   • Approach challenges with an open mind

   In their article Turning Obstacles into Opportunities: Agile for Technical Communication, Karen Smith and Patty Gale say we need to be “prepared to reverse our work. When you document features as they are being developed, there is a chance that stakeholders will decide a feature is not yet ready for release. Not only must the feature be removed from the product, but its documentation must also be removed.” The solution they suggest is:

   • “When you adopt Agile, consider how you will address such issues.
   • [At the start of a release cycle,] make a release management plan for the documentation.
   • Use a content management system with version control.
   • Develop a way to track the content that is added and updated for each feature. If a feature is omitted from a release, you can more easily ensure that its documentation is removed.”

2. Topic-based Approach

   With Agile, technical writers need to take a topic-based, modular approach to documentation (i.e., authoring concise, self-contained units of information about a specific topic). As features or deliverable working parts of features are developed and ready for testing, the writer needs to document the feature/functionality delivered in the current or following sprint. Content approval from BAs, PMs, and other SMEs on the content as written should also be obtained within the same period.

   As Austin observes, for Epics spanning more than one sprint, topics are a work in progress until the entire Epic is ready for delivery to the customer. It needs to be understood that more details or additional content may be added as further development is completed. The teams need to account for documentation deadlines that extend beyond the product development deadline. The key is to determine from the stakeholders what they consider a deliverable working partial feature that can be implemented in production and what needs to be documented, reviewed, and approved during a particular sprint.

   As is our current practice, we need to start writing content early in the development cycle to help with planning. John Collins suggests “another method for planning and getting started with writing is to generate content that is ‘good enough’ for now and version your results. This approach is the perfect application to writing in an Agile environment. Concentrate on what your users really need. For example, instead of shipping no document or shipping a document that’s a catalog of every interface element, you can ship a basic task-based document. Perfect form can come later.”

   Three things to focus on when taking the topic-based approach:

   • Task-focused Content—Focus content on what users need to do to get their jobs done. We need to write content so users can solve problems using our products. According to Alyssa Fox, “writing content targeted toward solving user pain points requires concepts, examples, and best practices information that don’t easily fit the user story model.” It is imperative to strive to deliver the most complete document set for each release.
   • Be a Minimalist—Focus on the smallest units of content for each user story and expand our documentation with contextual information as needed. We write documentation for a feature in the sprint in which it is developed and tested.

   Smith and Gale recommend that technical writers work in smaller chunks of content and iterate often. “As a technical writer, it may feel uncomfortable to not have all the information to document the product. This ambiguity can be unsettling. On the other hand, knowing that the product is likely to evolve in future iterations means you [can] further refine and improve the quality of the documentation before it’s delivered to users. Learn to chunk a large documentation project into smaller pieces. Work with scrum team members to break the documentation tasks into chunks that fit into a sprint, and share the load with others on your team to get it done. Identify documentation dependencies and plan them in your sprint scheduling. Flexibility and adaptability are the keys to making this work.”

   • Define Topic Requirements—The same type of content should be managed the same way. Define the requirements for each type of content presented to customers. Mark Baker states that every topic should adhere to a basic design that tells the writers exactly what needs to be said in each case. We need to implement topics … similarly expressed in a similar order. Per Baker, we need to define a specific and limited purpose for each type of topic—a separate template for feature overviews (including business use), prerequisites, concepts, tasks or procedures, references, etc. Once these are defined, content will be better organized for customer consumption. Since consistency breeds familiarity, we can provide improved customer satisfaction with our content.

3. Document (and Review) Continuously

   Scott Ambler believes that accepting the idea of documenting continuously is a good place for technical writers to start. If the goal of Agile development is to have a potentially shippable product or feature at the end of each sprint or group of sprints, then technical writers need to keep deliverable documentation in sync with software changes, and they need to write deliverable documentation continuously throughout the project.

   It also helps when drafted procedures and key concepts are reviewed as development is completed during the sprint. Not only will the functionality be fresh on everyone’s mind, a configured environment is more likely to be available for the technical writer to use. If you wait until the end of the release cycle, you may not have the right people available to review and approve the documentation because they have moved on to other projects. In addition, Alyssa Fox posits that “working on bits of the documentation throughout the release cycle frees up time toward the end of the cycle for consolidating final documentation.”

   Sparta’s customers are in highly regulated industries requiring ISO 9001 compliance. In Agile Under ISO: Review and Approval on Agile Projects, Ed Willis suggests the following documentation approval best practices to help to ensure a timely ISO 9001-compliant approval process for documentation:

   • Make the review process quick and within due dates and sprints.
   • Have as few approvers as possible. The more approvers there are for a document, the longer the approval will take and the more painful it will be.
   • Verify the accuracy of specific content for which identified technical SMEs have proficient knowledge.
   • Minimize the number of documents. As Ed Willis cautions, always make sure there is a compelling motivation for authoring a document; don’t create one unless there is someone who really needs it. When figuring out what documents to produce, involve the right stakeholders but favor making things that produce immediate benefits.

   Focused reviews, as mentioned by Willis, limit technical SME reviews to the specific content for which they have proficient knowledge and tell each of them where their specific attention is most needed. If, for example, you have updated only parts of an existing document, ask reviewers to concentrate on those areas. Make it clear that reviewers need not review the entire document unless it is actually necessary. This is consistent with the iterative nature of Agile and parallels the Agile code review process where small increments of change are reviewed. Code and documentation reviews are more focused and thus more accurate.

4. Agile Documentation: Digital and Online

   In Tech Docs as Agile Deliverables, Collins advances that “Agile technical documents are frequently updated and enhanced. They are no longer monolithic piles of information, but rather evolving, ever-improving, integral parts of your product.”

   To accommodate faster iterations of user documentation, Agile enthusiasts, such as Austin, suggest that user documentation is best distributed online. If your method of publishing documentation includes PDFs of entire guides or printed manuals, Austin points out that:

   Physical deliverables become more complicated. Agile will be harder to implement if you’re producing physical deliverables, such as printed documents. You won’t be able to iterate as often, but you could maybe do smaller print runs to give yourself a chance at more iterations. (This may not be realistic, but hopefully you get the idea.) You can still probably chunk out the production work into sprint-sized tasks.

   Communicate and Ask Questions

   Technical writing in an Agile environment means a lot of discussions, continuous communication, and actively working with various teams. If you are not being invited to meetings or discussions, speak up. Be sure to attend requirement refinement meetings and all demos at the end of each development sprint.

   According to Alyssa Fox and Meredith Kramer, “it is imperative you speak up in meetings and take the initiative to get involved in all aspects of the product development. Ask lots of questions. If you see something in a design meeting that doesn’t make sense to you, or you think there’s a better approach, say so. Don’t be intimidated by the fact you’re not a developer. It’s our job to look at the product from a user’s perspective. If a GUI is difficult to use, let the developer who’s coding it know. If you find out planning meetings are happening without you present, talk with the ones holding the meetings and make sure you’re invited in the future.”

   We all need to make efficient use of our time. Don’t waste time in meetings that don’t add value to the documentation.

   Agile relies on face-to-face interaction, frequent updates, and team members who are confident enough to volunteer input. Make sure this happens. According to the Agile Alliance, schedule meetings and suggest in the invitation “that answering the following questions will save attendees from having to attend the meeting produces results. If you produce the questions, there’s almost always someone on the team willing to give you answers. Also, be willing to do more digging and playing. You’d be surprised at how little you may need to get started.”

   Remember, communication is the key to every successful project!

Bonnie Demback is currently a senior technical writer at Sparta Systems, Inc. She has over 20 years’ experience as a technical writer in various industries, including years working for Dow Jones & Co., Inc. and Rutgers University.

References

Ambler, Scott. 2010–2014. “Document Continuously.” www.agilemodeling.com/essays/documentContinuously.htm.

Austin, Gavin. 2011. “A Writer’s Guide to Surviving Agile Software Development,” https://www.scrumalliance.org/community/articles/2011/september/a-writer-x27-s-guide-to-surviving-agile-software.

Baker, Mark. 2014. “Toward an Agile Tech Comm,” Intercom Nov/Dec, http://intercom.stc.org.

Beck, Kent, et al. “Manifesto for Agile Software Development,” http://agilemanifesto.org/.

Berry, Tana, and Ann Gentle, “Writing End-user Documentation in an Agile Development Environment,” http://justwriteclick.com/2007/07/02/writing-end-user-documentation-in-an-agile-development-environment/.

Collins, John. 2014 “Tech Docs as Agile Deliverables,” Intercom Nov/Dec, http://intercom.stc.org.

Fox, Alyssa. 2013. “Agile and Tech Comm: Task-Focused Content in a Feature Focused Process,” 11 August, http://techwhirl.com/agile-tech-comm-task-focused-content-feature-focused-process.

Fox, Alyssa, and Meredith Kramer. “Mobile and Agile: The Floating Writer’s Survival Kit,” www.writersua.com/articles/AGILE/.

Gonçalve, Ester F. 2014. “A Roadmap to Agile Documentation,” 15 July, www.infoq.com/articles/roadmap-agile-documentation.

Mazet, Jean-Luc. 2013. “Agile Technical Documentation,” http://writersua.com/articles/Agile_doc/.

Smith, Karen, and Patty Gale. 2014. “Turning Obstacles into Opportunities: Agile for Technical Communication,” Intercom Nov/Dec, http://intercom.stc.org.

Turner, Lee. 2014. “Adapting to Change: Why Make Plans in an Agile World?” Intercom Nov/Dec, http://intercom.stc.org.

Willis, Ed. 2012. “Agile Under ISO: Review and Approval on Agile Projects,” 27 Feb., www.o-act.com/index.php/component/content/article/
39-ed-willis/64-agile-under-iso-review-and-approval-on-agile-projects.html.