The not-so-agile technical writer

Limping through agile

on Jan 21, 10 • by Patti Murphy • with 2 Comments

I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me. Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong. But, it’s important to point out that our documentation team hit [&hellip...

Home » Agile Development » Limping through agile

I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me.

Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong.

But, it’s important to point out that our documentation team hit all of our deadlines for new features, while substantially rewriting our help set and moving it to a wiki. I’m pleased with the outcome, but the trip was not pleasant.

This will be my first post in a series about technical writing in an agile environment. Today’s post outlines the obstacles that I face—aspects of being me (mostly). The next post will outline my coping mechanisms, as well as our team’s plan for our next project.

If there’s no follow-up post, that means that my unbridled honesty has gotten my keester kicked to the curb.

Waterfall nostalgia

I got started on this tech writing gig as a consultant. The product would be a month or two away from release, but mostly fleshed out and I’d swan in, grab the requirements documentation and the design specifications (sometimes I’d write those), play around with the tool and voilà: a manual. I could be very single minded about what I was writing and just get it done.

To be clear, I’m in no way saying that the waterfall method delivered better products or documentation, just that I had a better view of where we were going.

With agile, I feel like I’m jumping hither and yon doing all these minute tasks, with very little view of how they’re supposed to fit together. I’d often snarl to my manager after meetings that “I’m given a doorknob, a shingle and a shrub and told to go build a house with them.”

In fact, in his blog post about minimalist documentation and agile, Shannon Greywalker hits on my problem very accurately, and it’s this: “user stories are typically too granular” for minimalist documentation. Minimalist documentation, as he says, requires the “35,000 foot view”.

And what I want runs counter to the whole agile methodology: THE BIG PICTURE RIGHT NOW.

Multi-tasking versus uni-tasking

Another problem I face is that I’m a uni-tasker; I like to finish what I start—not doable when features span several development iterations and are in major flux.

There are blogs out there about what Generation Y is like, good or bad, but the one thing I do envy is their multi-tasking ability. These folks grew up doing homework, while downloading music and instant messaging their friends.

That’s the kind of splintered attention I envy. So, I got David Allen’s book, Getting Things Done, but I couldn’t finish it. I read the line about having “a mind like water” and then froze. Uh-oh. Mind like ice. When I think of my work and personal to-do lists, I’m paralyzed.

So, I signed up for meditation classes and I’m now making another attempt to read Getting Things Done. I’m hoping it’ll help me switch directions faster. Not easy when you feel like the Titanic and need an hour’s notice to hang left. Now that I think about it, the Titanic is a career-limiting metaphor.


Now it’s time for confession. Our documentation department fought for and won a two-week offset for our last two projects. Yep, that’s right, we trailed development by a two-week iteration.  It’s amazing that we haven’t been rounded up and thrown in agile jail.

By procrastinating this way, we hoped that features would be more fleshed out before we started writing about them. It was our vain hope that this would contain some of the rewriting efforts. We still did a lot of rewriting, but this round we were rewriting a lot of material for the wiki anyway, so the offset didn’t matter that much.

By now, you’re probably thinking that it must be very hard being me. Don’t cry for me, Costa Rica; I have ways of getting by. Tune in whenever the next post surfaces to find out how I cope and how I hope to improve.

Related Posts

2 Responses to Limping through agile

  1. Melody Locke says:

    I’ve been working in agile environments since early 2005 and found it to be a refreshing change from waterfall. I think that the developers and testers had more challenges, but after they settled down with the new methodology, my life was pretty good. In waterfall I had to use specs that were out-of-date the moment they were finished. I followed those documents, while my developers use them as guidelines. As you might guess, rewriting was a big part of my life in this scenario.

    As for the “big picture,” that should be addressed in release planning. At the end of a successful release-planning meeting, I had a pretty good idea about what would be developed and where (in the release cycle) the work would occur. I know that many writing groups trail their development counterparts, but I’ve been a part of good teams where I was able to write content and have it tested during the development iteration.

    Not all of my agile experiences have been as good as my first. Now my developers are located on the other side of the world, which makes staying current with development is bit challenging.

    • Patti Murphy says:

      Hi Melody,

      I’m pleased to hear that your experiences have been so positive.

      Geographically-dispersed teams can make things even more difficult. A number of our developers are based in Russia, but they’re prompt in answering e-mail inquiries and providing examples.

      I typically haven’t gotten enough to write about from iteration planning meetings, just a general notion of what’s coming up. With “feature flux”, it seems that you can only give a general “what-this-is” statement instead of “how it works” because the latter can change quite a bit. Often, our focus starts with “why you’d want to use this” and then go from there.

      In my limited agile experience, new products have been easier to document than new features to existing products. With the former, workflow is more readily available.

      Thanks for your perspective.

Leave a Reply to Melody Locke Cancel reply

Your email address will not be published. Required fields are marked *

Scroll to top