LavaCon 2014: Alyssa Fox on Targeted Content and Agile

Targeted Content and the Agile Whole Team Approach

LavaCon-Session-targetedcontent-agilePresenter: Alyssa Fox, Director of Information Development, NetIQ


As part of Adobe Day at LavaCon in Portland, Alyssa Fox gave a presentation on “Targeted Content and the Agile Whole Team Approach,” a subject she has previously covered here on TechWhirl.

I am summarizing Alyssa’s presentation and also giving my own spin on it based on my own experiences with software development, and as a technical writer and manager. Alyssa Fox is Director of Information Development at NetIQ, and she is clearly passionate about involving her team in the software development process.

In a typical Agile development process, documentation and quality assurance tasks tend to lag behind development tasks. This means that a feature can be complete in the software and integrated into the product before it is either tested or documented. However, this approach can lead to all sorts of problems. For instance, as you come up to the inevitable rushed deadlines for releasing the product, do you want to include these features that are already there but which are not properly tested or documented? Are these features really done?

Alyssa distinguishes between “done” and “done done.” No feature is “done done” unless it has been tested and documented. So the trick is to see the development, testing, and documentation of a feature as something that should be done in one sprint, rather than dividing these tasks over more than one sprint. In my experience, if all the tasks have not been done in the one sprint, it can slip into the next, but the idea of keeping all three tasks together is important. Alyssa emphasized the shared responsibilities, the fact that all teams must provide estimates, and the new perspective and vision on what “done done” means.

Indeed, I have found that many of the problems with software products arise because documentation and quality are afterthoughts to development. If a developer with a perfect setup can get that feature to run, under some (quite likely not-real-world) circumstances, the organization sells that feature regardless of whether it is usable by the general customer base. I think of software development tasks as being analogous to an iceberg: maybe 20% of the work relates strictly to software development, and the other hidden 80% is done by technical writers, testers, marketing writers, usability experts, product managers, and others. The hidden 80% is often regarded as dispensable. But a mature software company realizes the importance of all members of the team.

Alyssa talked about ensuring that her team uses the product and helps perform test cases. I agree with this philosophy, and I try to implement it, even for highly technical software used by experts. I am often challenged by trying to duplicate a real-world environment. For example, when working at one software company, I spoke to users who used the company’s product on a file with millions of records, whereas I used test files with a few dozen records when creating documentation. (Perhaps the challenge of understanding the user’s environment, and ideally duplicating it, is a potential topic for an upcoming tech comm conference?)

Alyssa also reviewed best practices for writing targeted content for users. Take a look at her well-described and concise summary:


In particular, the advice to always consider what the user needs to know, and not what “you” need to know, is of paramount and constant importance when writing technical documentation.

Alyssa’s team helps define acceptance criteria, participates in regular user interface reviews, and handles backlog grooming. The acceptance criteria means that the team agrees ahead of time on what the capabilities of this feature will be, which helps prevent last-minute misunderstandings and calls for increased functionality. Backlog grooming ( gives her team a significant voice in determining the future of the product. I am sure her team appreciates these chances to move beyond the circumscribed bounds of traditional user documentation and learn new skills.

The NetIQ information development team abides by this exceedingly on-point quote from a developer, Oleksi Derkatch:

It’s better to have 80% of the features 100% done, instead of having 100% of the features 80% done.

Indeed, without the oversight of a disciplined eye to ensure that a feature is truly done, it is easy to have a hodgepodge of “not-quite-done” features. Do less, but do it well.

Alyssa is an advocate of “Zero Bug Tolerance.” In principle, I agree. But salespeople might argue that fixing a small bug, or even a cluster of small bugs, is inconsequential, in comparison to developing a new feature that may potentially sell hundreds of thousands of dollars’ worth of software in the next release. All software has bugs; determining the importance of fixing these bugs compared to other development tasks is a balancing act. I would like to hear more about companies that follow the “Zero Bug Tolerance” principle.

Alyssa finds that the “whole team” approach improves teamwork and quality. I compare it to the difference between the old assembly line methodology for manufacturing cars—where the car is sent down the line with people working in isolation on just their tiny piece of it—and the Volvo approach, which features teams that work together to manufacture the car (a simplistic comparison, but applicable to the big picture). Team engagement happens where people feel part of a team and are personally invested in the process. Whether or not your software development team follows a specific Agile approach, you are almost certain to get better results if the technical writers feel like they are an active and valued part of the team.