Agile & Tech Comm: Can This Union Work?

April 13, 2010

If you follow me on Twitter or LinkedIn, you already know I’ve been having a small coronary over my team’s planned shift to Agile.  For us, this means moving from an annual software release schedule to a monthly one.  And if that wasn’t enough of a shock, this statement on the Agile Manifesto was:

Working software over comprehensive documentation

Gulp. Does this mean Agile teams have no room for Tech Writers? On the contrary, my research is proving the inverse: Tech Writers NEED to be on these teams.

Brief aside: one thing you should probably know about me – when something makes me anxious, I research it. In fact, I research the hell out of it until I start seeing it my sleep. It’s how I beat those mountains back into tiny molehills. So, while running around my office with my heart palpitating, the statement above implied “Working software over documentation.”

No User Guides? Surely, you must be joking. (Who will make the first Airplane! reference?)  My research taught me this is a common misconception in the Agile world. Programmers worried this meant the end of comments. Project Managers worried that requirements, planning, and tracking documents would be abolished.

But that isn’t what the Manifesto actually says.  The statement contains a qualifier: comprehensive.  Its presence in the statement changes everything.  Comprehensive carries a range of implications.  Have you ever resented having to complete numerous reports and spreadsheets only so they could be checked off some master project list, even when they don’t make sense from a user perspective? Or delivered certain information products only because they’ve always been in the doc set?

Folks on Twitter and LinkedIn have posted a bunch of links and I’m learning that Agile teams are empowered to determine for themselves what comprehensive and documentation look like.   For example, not all tasks can be adequately taught in a traditional user guide.  As computing power moves increasingly to the cloud, I’ve learned that screencasts, Wikis, and blog posts offer more accessible, comprehensive and deeper coverage of certain software tasks than the straight user guide.  Agile, I think, makes us examine user needs, challenging us to no longer deliver the same manuals just because that’s what we’ve always done, but to make sure that’s what users want and need and will use.

A surprising result of my research was the reminder that the less-traditional writing work we do on a daily basis is not over. GUI screen editing, error message drafting, illustrating, design testing, and so on… this work can, indeed, should be included in work estimates.

Here are some of my favorite links:







My gratitude to Anne Gentle for the links and emails you sent, to Sarah Maddox for the sheer volume of experience you share regularly, to Diana Ost for her ‘day-in-the-life’ accounts of being an Agile Technical Writer, and to everyone who commented on LinkedIn.  You’ve all given me lots to digest but I realize the only way to learn Agile is to be Agile.

Stay tuned.



  1. Hallo Patty
    Great post. Neat closing: “the only way to learn Agile is to be Agile”! As our company’s use of agile methodologies matures, we’re finding that the tech writers are becoming more and more valued. The development and product management teams consult us in the early sprints, for input on UI as well as online help and documentation. I’d say, if anything, we’re even more flooded with work than in a waterfall environment. As you’ve pointed out, the words “Working software over comprehensive documentation” are open to interpretation and indeed to restyling. Perhaps the UA (user assistance) is now more part of the “working software” than ever before. 🙂
    Cheers, Sarah

    • Thanks for commenting. I’m so relieved to hear tech writers are becoming more valued in your experience. It’s gratifying to hear that teams recognize we do more than proofread.

  2. Switching to an Agile method was one of the best things that happened to my old team. Before Agile, we had to guess at what was being developed or learned about everything at once with a week left to deadline. With Agile we were integrated into the dev team more, had complete visibility as to what was being worked on by who and knew when something would be ready to get our hands on.
    We didn’t even think about the “working software over comprehensive documentation” idea – it didn’t apply to what we did as tech writers – it applied to the developers and their planning docs and specs – we were still able to create docs we wanted/needed even more efficiently than ever before.
    I miss that old team 🙂

    • Thanks for commenting. I hope to experience being a true part of the dev team, as you mentioned.

  3. Good stuff, Patty. I’ve been pondering these things too: http://www.sdicorp.com/Resources/Blog/articleType/ArticleView/articleId/115/Good-enough-but-what-about-the-details.aspx

    A couple of thoughts:

    I think that “documentation” in the manifesto refers to internal documentation (such as engineering specs) as much as it does to customer documentation. (tjrainey made this same point above.)

    For customer documentation, the emphasis should be on content that supports the user stories — in other words, real users doing real tasks — rather than on documenting every detail about the product. I can get behind that.

    Finally, I’m heartened by the fact that most writers who move onto Agile projects find that they like it.

    • Thank you, Larry, and for linking. I am much less frightened now and find myself looking forward to it.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: