How to be an Agile Technical Writer with a cool acronym like XTW

One reason why I like the show Dirty Jobs so much is because Mike Rowe, the host, is so respectful and honest about the work that people do each day. Dirty Jobs offers such a great viewpoint on work that is done each and every day. I recently discovered that Sarah Maddox, a technical writer at Atlassian (makers of the Confluence wiki engine), has written two great posts about being an Agile technical writer, or an eXtreme Technical Writer (XTW). These posts on Agile Technical Writing offer wonderful windows into the work that technical writers are doing around the world. Plus, they offer some down-to-earth how-tos that make sense to apply in a modern technical writing career. If you’re thinking about technical writing as a career, check out these two posts for your research, because I believe that agility is one of the best skills you can bring to this career path when I consider the direction it is heading.

  • Plus don’t miss the great photo art mashup in the agile technical writer part II, another excellent post that really describes what it’s like to write in the Agile development environment.

Here are some highlights from each that I could identify with:

  • Responding to IMs from all over. Carrying on multiple conversations intelligently is a gift.
  • Concerns about information overload – it’s daunting, but do-able. (Okay, funny side note – My typo for overload was “overlord.” Yipes. That can happen too.) My advice is to ride the serendipitous river of information. Sounds like hippy advice but somehow it works.
  • What a wonderful viewpoint of how the daily life of a technical writer has changed so greatly over the years. I listened to Linda Oestriech’s podcast about the Direction the STC is Heading at Tech Writer Voices and one great quote from her was, “We’re not the technical writer from the 70s.” I’d say we’re not even the technical writer from the 90s.
  • Love the Swaparoo idea – similar to pair programming, but call it a swaparoo when you want to trade tasks with another writer to get cross-product knowledge.
  • Respond to customers from the varied means of communication that is offered to you in this awesome world of documentation. And if it doesn’t have to do with the doc, don’t meddle, pass it along to the support team.

Thanks Sarah, for sharing such a great “day in the life” slice for technical writers.

Authoring and delivery tools for the Agile Technical Writer?

I’ve had a question via email recently, asking something like, “What is the ideal toolkit for writing in an Agile environment?” Or, “What would you choose if you had to write in an Agile environment in order to be most effective as a technical writer?”

It’s tempting to actually try to answer that question with a straightforward response of one tool – but of course the answer is not that easy. The product and audience and company that you’re writing for all dictate the documentation deliverable with far more weight than the “manufacturing” process that is used to build the product. Sarah’s posts don’t directly mention their toolkit, but her “eat your own dog food” bullet point hints that the doc is delivered via their wiki engine. (Sarah, do correct me if that’s an inaccurate leap in logic.)

But, if the product you’re documenting isn’t itself a wiki, you’re going to need to evaluate tools. I borrow directly from Don Day’s editor evaluation heuristic for a methodology for evaluating a writing and publishing toolkit to fit in an Agile environment. Evaluate a tool (no matter what you’re trying to deliver or how you’re authoring it) using “cost/benefit judgments on the features that mean most to your intended scenarios, business rules that need to be supported, and the willingness of your team to learn some new ways of doing things.” Well stated, Don, and whether you’re trying to find the right DITA toolkit or the right Agile toolkit, scenarios and business processes are quite useful. Anyone have great authoring or publishing scenario or business process suggestions for the XTW?


  • ffeathers
    February 20, 2008 - 4:38 pm | Permalink

    Hallo Anne

    Glad you like the ‘XTW’ acronym πŸ™‚

    You’re quite right in assuming that we use Confluence wiki for our technical documentation. (The ‘eat your own dogfood’ thing.) We use the Confluence wiki to document Confluence itself, as one of our products. And we also use it to document almost all our other products (Bamboo, Crowd, Clover, FishEye and Crucible). Our JIRA documentation is currently held in Apache Forrest, but we’re planning to migrate it some time soon.

    I agree 100% that you need to evaluate a few tools, if you’re given the luxury of choice. First, define your requirements: a wiki wouldn’t be the most logical choice if most of your readers are offline, for example. And there’s a whole lot of really interesting analysis going on, about structured documentation (DITA, DocBook) and tools like RoboHelp versus wikis. Eric Armstrong has some interesting points on his Cool Stuff blog.

    Your own blog is choc-a-bloc with really good ideas and pointers too. I’ve been following it for a few months now, and I’d recommend to new-comers that they take a look at some of your past posts too πŸ™‚

    Seeya on the page, Sarah

  • April 2, 2008 - 11:31 am | Permalink

    Thank you for posting such excellent insights. I’m trying to get our developers to understand that the writers need to be part of the agile process (not just chickens on the pig ranch; not scowled at for asking for a technical review here and there, or asking, “Is this how it really works?). Wonderful; thank you so much. We (writers) can’t write documentation to support vapor-ware; we try to read minds but don’t always succeed. We can absolutely write documentation to support what you’re designing and developing, and if you just nod or shake your head, that’s all we need. πŸ™‚

  • Pingback: agile project management

  • Leave a Reply