A Glimpse into the World of Agile Technical Writing, a.k.a. Extreme Technical Writing (XTW)

by Tom Johnson on Feb 19, 2008
categories: technical-writing • wikis

Sarah Maddox gives us a interesting glimpse into the life of an agile technical writer, or more descript, extreme technical writing, XTW. If you work in an agile environment, definitely check out these two posts:

• The Agile Technical Writer (I)
• The Agile Technical Writer II

(Although ffeathers is already in my feedreader, I missed these posts in the firehose of information and didn't discover them until I read Anne Gentle's latest post, How to be an Agile Technical Writer with a cool acronym like XTW.)

Here are a few excerpts from Maddox that hit home with me:

Things change, and we need to change with them. If we spend too much time setting requirements in stone, they're out of date by the time we write the software. And then there's no hope that the documentation will be up to date.

Totally agree with this one. I went from a traditional all-requirements-up-front environment to an agile environment, and the difference in software quality is pretty astounding. I'm convinced that people don't know what they want until you deliver them an actual product.

The documentation, like the software, is not written once and then left to decay quietly. Instead, writing the perfect document is an iterative process:

• Write the page, get it reviewed, and publish it as quickly as possible. There are people out there who need it now!
• If you find a programming quirk while documenting the software, let the developer know.
• When the developer changes the code, make sure the documentation is updated too.
• Respond to comments from customers, developers, support staff and anyone else. Update the document immediately.
• Monitor changes made by other people.

This is certainly a shift in mindset. Your docs aren't done when you release the product. You just begin revising them after you release them. (Well, take a break for a week at least.)

Get with the eat your own dogfood thing. It really works. If at all possible, make the products you're documenting part of your daily life. That might be difficult if you're doing the techdocs for NASA or MI6 or something. But hey, a flaming rocket or a poison pen might just come in handy at the next standup

I couldn't agree more. You don't completely learn a product until you actually use it in the same context and purpose as your users.

Subscribe to blogs, wiki watches and anything else that's going. Some people may tell you that you'll die of IO (information overload). But that's not so. You'll quickly learn how to scan the stuff coming in and pick up on the relevant bits. It's the only way to stay ahead of the agile environment.

This use of wikis caught my attention. I think that in this context, an agile environment where things change quickly, and developers are expected to keep you in the know, a wiki might be useful -- especially a wiki with RSS feeds.

As a technical writer, my aim is to reduce other people's work, by making the documentation as simple and useful as possible. It takes a lot of work to achieve that simplicity. But it's awesome because it's what I love doing.

Simplicity is an extremely important ideal in technical writing. I'm not quite sure how to achieve it. Our job is to make the complex simple, but if you leave out the advanced info, your help is useless to the power users, and if you include too much of the advanced info, it doesn't help the beginner. I thought I could simplify it all through drop-down hotspots, but these hotspots becomes problematic for single sourcing --they don't allow you to break up your help into easy mix-and-match discrete topics.

Respond to requests from customers. They may come at you via email, phone, comments on your documentation pages, etc. If the comment is about the documents, that's your job. If not, pass it on to the support team.

Amen to the tidbit about passing them off to the support team. You're an expert on your app because you just documented it inside and out, but the minute you offer to help a customer, you open the door to an oncoming freeway of phone calls and emails.

More on Agile Documentation

I'm in an agile environment, but I wouldn't consider it extreme technical writing. Everything is coordinated through JIRA -- user stories, bugs, enhancements. Nothing changes to the app without something being entered in JIRA. As long as I keep aware of what's going on in JIRA, I'm in the loop.

I'm still not converted to wikis -- I've just never seen a development team and user base contribute to a wiki with any significance. But maybe if I worked for a company that actually made wikis, like Maddox with Atlassian Confluence, I'd have a different experience.