Technical writing and software design—is Agile development the way to go?


A report on the May 18, 2010 program meeting by Catherine Kerr, with photographs by Pam Drucker and Marika Piehler.


Published: June 2010

This program year, our final event coincidentally sustained the theme of teamwork strategy that Ben Hechter had explored the month before in his witty and wise talk about project scheduling. The planned topic for our May 18 meeting had been the use of personas. Instead, when an emergency forced our scheduled speaker to cancel, the day was saved by three experts on a different subject –the pros and cons of Agile development from a technical writer’s point of view.

The substitution suited my own purposes very well. I was happy with Plan A, having seen success with website content that speaks precisely to well defined user personas—but that same experience made me curious about Agile development, Plan B. I wondered what kind of challenges an Agile team would present to today’s senior managers. And what about their direct reports? Are there sophisticated new ways, I wondered, of harnessing self-managed teams?

Panel teamwork

For Plan B, the chapter owes a debt of gratitude to panelist Susan Patch, whose ordered thoughts about Agile teamwork had been up her sleeve for some time, and also to Lois Patterson for stick-handling the program substitution and for moderating the session.

Susan was joined on the panel by David L. Drucker http://www.drucker.ca/. Whereas Susan is on staff at Galdos Systems, Inc., David is an independent contractor specializing in user interface architecture. David’s blog, loudmurmurs.com, introduces him as a musician-turned-technologist who is interested in certain outcomes from devices and software—not how they can make money but “how they can make people more powerful, creative or connected to others.”


Panelists Tony Chung, David Drucker, Susan Patch, Lois Patterson

Providing a third perspective on the merits of incremental development was Tony Chung “Tony Chung http://tonychung.ca, often viewed in our chapter as the CMS master who always looks under the hood. Tony’s site confirms his interest in systems—he doesn’t just produce and present content through various media but develops systems for this purpose.

After introductions and voicing their answers to Lois Patterson’s first question, the panel went into fishbowl format. Later on, Pam, Helen, Gabriel and Eagranie all took their places in the fishbowl—mostly by inadvertence, but with good grace.

Lois lost no time with easy questions, challenging panelists first to tangle with the central issue raised by Agile techniques:

“How do you reconcile flux in interaction design with flux in code at the same time?”

Susan, who has always done software documentation as part of an engineering team, addressed the value of positioning technical writers in an interpretive or middleman role. Interaction design is always in flux, said Susan, whatever the teamwork style: problems come up, and in Susan’s view Agile teamwork is well named for its ability to apply specialized skills to problems as they arise. Take the example of engineers finding they can’t build what designers envision. Have the interface designers grasped what engineers can do and what they want and need? Fingers could be pointed in both directions, putting the sprint off track. Contributing a third perspective, a writer can help the team define the obstacle impartially and surmount it together.

David responded with a contrast to the Agile process, namely establishing a metaphor that gives the final product life and shape in its developers’ minds so that they don’t become too immersed in process. David also spoke of the overall concept as a point of rest for the software, in itself a strong image that suggests the opposite of obsessive tweaking. Confirming the benefit of a broad schema, another participant pointed out that without one, designers may have to sit through many sprints wondering, “Where can I fit this new feature in?”

And yet there are payoffs for building and documenting something that is “,good enough,” production-line style, even if it is a simple project like one of Tony Chung’s early websites. The client told Tony to construct the site as if he were building a summer cabin: the result of Tony’s work would not be worthwhile unless it was ready when the users needed it, but it wouldn’t be perfect, either. “Some walls may have to come down.”


Gabriel Gosselin, Eagranie Yuh, Helen Glavinas, Pam Drucker

Waterfall versus Agile

There was general consensus that the “waterfall” method of development is better in theory than practice. Competitive pressure compresses the available time from conception to market, and that pressure is ever greater. There will never be enough time to define all the features and attributes of a project in advance, detailing the subordinate steps, and then do the work in strict order with the technical writer bringing up the rear.

User feedback can spring surprises, too. There’s slippage between what users really want and what they state they want when asked in advance. In any development process, code has to be thrown out. Sometimes that is because the developer has a different definition from the user’s for a field that is pivotal to the design product. (When a fridge user wants her food made cooler, does she turn the control up or down? An engineer’s logic may not yield the right answer.)

Tools and supervision

Susan made the case for sprints that incorporate user feedback, especially supported by mock-up tools. These, in Susan’s opinion, are now advanced enough to mediate good communication with users. Susan cited Balsamiq in terms that had audience members scribbling on their napkins. Conversely, that old standby, Visio, got a reasoned endorsement from Tony Chung, who saves drawing time by programming connections in advance to create a pull-down list.

Whatever their tools, it is axiomatic that in Agile teams, the different specialists must collaborate. How much supervision does that take? Maybe none. Susan described the merits of a self-organizing model for teams, though she admitted that the idea is a hard sell to any but the most sophisticated managers and owners. On that point, there was general assent.

“Does the Agile process increase the number of bugs?”

Pam Drucker weighed in on the next question—“Does the Agile process increase the number of bugs?” In Pam’s view, working in sprints with user input won’t necessarily help speed up the remedial cycle. Pam’s experience is that if there’s a bug, the engineers can tell you before the users will. Many glitches are preventable if team members don’t specialize too narrowly but instead show interest in each other’s work; for example, if UI designers are aware of languages engineers are using.

The next entrant to the fishbowl, Gabriel Gosselin, contributed the perspective of a project manager working in the cauldron of electronic game design. Originally a technical programmer, Gabriel appreciates that game development requires “paring down the parts.” There’s also a great need for intermediation, something writers can do. On one of his teams, for example, the artist had great vision and a superior command of Flash but, without guidance, could not give engineers something to work with. As a debugging programmer, says Gabriel, he didn’t stop at patchwork correction. His instinct was to trace problems back to source—if X doesn’t make sense, then something is wrong with the structure of Y files. Like Susan, he now sees his function as “integrator,” smoothing communication between designers and engineers. “Territory is always an issue—our job versus my job.”

Collaborative reflexes

The excitement and huge gratification of polished teamwork under deadline pressure was captured in Susan’s story about a weekend of tag-team labour before a shipping date. Problems fell like dominoes, as she described it. One reason, seemingly, was that pride no longer prevented any group member from signaling when he or she was stuck. Another was that, over a year’s time, the team had developed collaborative reflexes, becoming ready to drop everything and huddle around the one with the show-stopper problem.

But teams always take time to jell. Do company dynamics give teams the necessary time in constant meetings to master Agile technique? How many managers are even willing to see meetings as an investment rather than an expense?

The biggest challenge in Agile development, panelists suggested, is writing the business case for the approach. Due diligence would seem to require a business case, but the measurements behind the business case for Agile teamwork fall outside accounting traditions. Can you quantify the results of early meetings? They are probably too intangible. Can you trace results to synergies between individuals? Those synergies probably change from meeting to meeting. Can you project if the team’s problem-solving ability will accelerate, and if so, by how much?

To foretell how an Agile project will go, specialists have to achieve a degree of mutual trust that usually comes only after intensive teamwork. If trust is a precondition of teamwork, but only team experience forges the needed level of trust, how can a company foster an Agile team? I was left thinking that the emergence of Agile teams must resemble how Web teams got their start as skunk works in companies with a rigid IT culture. Indeed, someone described the impetus for Agile team formation more as grassroots rebellion than business case management. In that respect, there is continuity from the earliest of Web geeks to the nimblest new Agile team.

Fishbowls (with thanks to Wikipedia)

A fishbowl conversation is a form of dialogue in which a large group can actively participate. To start it off, preselected or volunteer participants occupy a few focal chairs, one focal chair is empty, and the remaining group members are seated outside the fishbowl. A moderator seeds the discussion with a sequence of questions, recognizes input from the audience, and referees as needed.

In an open fishbowl, any member of the audience can, at any time, occupy the empty chair and join the fishbowl. Our chapter’s fishbowl rule is that an audience member who offers a question or a comment must then occupy the chair.

If the plan is for preselected subject experts to remain involved throughout, none of these panelists leaves the fishbowl. The empty seat is merely traded as participants enter and leave from the audience. If rapid, such a succession can bring much of the audience into the dialogue. When time runs out, the fishbowl is closed. Often the moderator summarizes the discussion.


©2012 STC CWC | Home | .(JavaScript must be enabled to view this email address)