The agile technical writer

One of the four basic principles of the Agile Manifesto is to value ‘Working software over comprehensive documentation‘. Oooo-er! Documentation devalued — that cuts technical writers out of the loop. Or does it?

Hallo, I don’t think so πŸ™‚ The technical writer’s role has become even more interesting, exciting and above all, valuable — that’s what I find, anyway, now that I’m working in an agile development shop. And we’re extremely agile. We have seven core software products plus two hosted platforms, making nine products in total. Each product has a release cycle ranging from a couple of weeks to three months, give or take an iteration. That keeps us all on the hop.

The main thing is that you have to be, well, agile. This blog post is all about the Agile Technical Writer, even the Extreme Tech Writer — let’s call her the XTW.

The agile technical writer

Here is the preamble from the Manifesto for Agile Software Development:

We are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value:

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

I’ve found that the aim of having less comprehensive documentation applies primarily to the beginning of the traditional SDLC (Systems Development Life Cycle). In an agile development team, there tends to be a less comprehensive process around the feasibility study, business requirements investigation and functional specifications. That’s typically the domain of a business analyst rather than a tech writer, though the roles are very similar and often intertwine in very interesting ways.

A technical writer’s strengths really start to shine at a later stage, after the developers have had a first stab at writing the code. For the XTW (agile/extreme tech writer, for those who’ve just tuned in) this means that our role is even more interleaved with the business analyst and quality assurance roles. But it’s a matter of emphasis rather than a change.

The emphasis is on responding to our readers’ needs and producing high-quality products.

It’s just good fun as well as good sense.

A day in the life of an agile technical writer

  • Get in early and hook up to my feeds — see what’s happened to the documentation wikis while I’m asleep and the other side of the world is at play.
  • Trickle around the standups (short meetings held standing up), first with a development team or two and then with the tech writing team.
  • Play with the products and write the documentation.
  • Click on a flashing IM (instant message) from a developer who wants some advice on the text for an application screen.
  • Attend a super-short presentation by the development team of a new feature that needs documenting for the next software release.
  • Weather an IM blizzard from a support engineer half-way across the world, who has a customer with some interesting (synonym for irate) feedback on the documentation.
  • Try out a new feature and report behavioural quirks to the developer. The tech writers are often the first β€˜real’ people to try the new feature. (Everyone knows that developers reside primarily in virtual rather than meat space.)
  • LOL in response to an IM from a fellow tech writer, who has spotted one of those things that only tech writers find funny.
  • Take a look at comments rolling in from customers on my space watch. People often put very useful comments on the documentation pages, which we can incorporate into the page. Other comments, usually by some dude called ‘Anonymous’, are not so constructive and may even need radical elimination.
  • Have a quick chat with a developer in meat space, to find out what bits of new functionality I might have missed.
  • Respond to a software emergency: Add a note to the wiki about a just-discovered bug in the latest release, give the stressed developer a chocolate and start the release notes for the patch.
  • Add myself as a ‘watcher’ of a just-reported bug that will require a documentation update when the issue is resolved.
  • Go and play with the WII in the lunch room.

‘Today I bought a bikini’, or ‘What about procedures?’

Myself, I’ve never been keen on procedures. If you’re going to do XTW, it’s more rewarding to go all the way. It’s a bit like buying a bikini (as I’ve just done today): the skimpier the better, otherwise it just doesn’t work and what’s the point anyway.

The agile technical writer

We’re a team of four writers. We have a wiki, where we put our guidelines and other interesting titbits. Did you know that Americans spell the last word in my previous sentence as ‘tidbits’? After writing the word, I realised that it might have an unfortunate association with the topic of the previous paragraph and picture, and I even contemplated changing the spelling. Is that why the Americans did? 😳

Rather than stating ‘This is how things are done,’ our guidelines are more along the lines of:

This is what’s working for us right now.


Hey, this is awesome, you might want to use it too.

A while ago πŸ˜‰ a dude named Ovid said that everything changes and the only constant thing is change itself. He wrote a book about it, called The Metamorphoses. In his world, the situation was a bit out of hand. People changed into trees if they stood in one place for too long, gods transformed themselves into swans to fool a passing virgin, and the meringue of civilisation constantly threatened to crumble into wisps of sugar-coated nothingness.

Things haven’t changed much since then. (Paradox alert!)

I’d say that’s the main reason why the Agile Manifesto works. 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.

As a team of XTWs, we talk about the team and our interactions with the rest of the company. We adapt as quickly as our environment does.

And we keep the documentation moving too. 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.

Past, present and future

Here’s my take on life, the universe and technical writing:

  • Ovid is 2000 years old but still rocks.
  • Long meetings and unwieldy email discussions are outdated.
  • Standups, RSS feeds and wiki watches are working right now — but they’ve been around a while already.
  • Tomorrow is an unknown, but it’s gotta be different.
  • Documentation will survive πŸ™‚

Saving the best bit for last

I really like this bit of the Agile Manifesto:

Simplicity–the art of maximizing the amount of work not done–is essential

It’s a paradox. (Another one, and what would we do without them.) 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.

I guess that’s what’s behind the Agile Manifesto too.

Our team has picked up some great techniques over the last few months. This blog post is getting very long, so I’ll save them for my next post. Happy extreme tech writing!

Update: I’ve added some hints about techniques our team has learned in another post: The agile technical writer II

Update August 2009: Atlassian has just published a new section of its web site, called “agile@Atlassian”. There’s a section on how the technical writers do agile. There are videos too, including one of me (spooky). Go tech-writers@agile@Atlassian.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 20 January 2008, in technical writing and tagged , , , , , , . Bookmark the permalink. 31 Comments.

  1. Interesting post. It’s got me thinking on how the handle my next round of updating design document templates. Because our SDLC is quite unique, and we’re not ready to move to an Agile method, it’s interesting trying to get this type of thing done. However your comment about “This is what’s working for us right now” has got me thinking. Because I’m already working on redoing our internal wikis, I’ve been toying with the idea of using them to explain the “templates”, which are more like “guidelines” and “things to consider” when they’re being written. Sometimes my non-TW colleagues tend to think “template” is something that’s firm and can’t be changed, even when I tell them that it is more of a guideline than anything else. I just want them to write things down! πŸ™‚ So I’ll be keeping this whole “use the wiki for templates, and call them guidelines instead” in mind in the next couple of weeks. May help us out.

    (And sorry if this post is somewhat rambling…I’m just too tired from life to go back and redo it. πŸ™‚ ) Cheers.

  2. Hi Sarah,

    I just wanted to wow your blog. I’ve only read 2 entries, and already I’ve been nodding my head the whole time.

    Seems that, I too am an agile technical writer, or more accurately am in the midst of becoming one (but that’s agile for you, isn’t it? :)).

    Anyway, be sure I’ll continue reading. A lot of thing you’re writing hit home, since GigaSpaces also works according to Agile practices, and we also have wiki-based documentation. However, “we” are still a team of one, so I’m still trying to keep up with the R&Ds crazy progress. All the things you manage to fit in to one day are quite admirable.

    Thanks for the reading, continuing to do ATW (since I’m not sure if I’m a XTW yet) stuff.

    Good day,


  3. Hallo Limor

    Thank you for your comments πŸ™‚

    And a huge congratulations on winning the the STC’s Award of Excellence for the Gigaspaces documentation wiki!

    A team of one, that’s impressive. I’m thinking you must be very agile indeed and can surely claim the magic ‘XTW’ acronym.

    Seeya on the page,

  4. Hello

    I am looking for a little guidance. I have been a tech writer for about 3 years. I like the work, but I sometimes wonder how good/productive/effective I am.

    Exactly five weeks ago, I began a contract position for a large comapany. I love the people and the company. In the second week, I was given two assignments. Both are instructions for manufacturing electronic equipment and are about 150 pages long. One was an original document that I was told was 95% complete. I have gone through two sets of redlines with the SME, updated the formating, taken two sets of pictures and still need more. I have also been told that the reference numbers for the parts are wrong and need to be changed. While this document was in review, I worked on the second document, which was only supposed to be a revision. It also needed format revisions and style updates. Neither document is complete. The second is in review with the SME, but I don’t think it is finished. Am I too slow?

    I really would like to make this permanent, but worry that my efficiency is not as good as they had hoped. Can someone with experience, who is not competing for my job, please help me?

  5. Hallo Jewell

    Two documents, each 150 pages long, is a big task. It’s hard to say how long such a review and completion job would take, without knowing the original quality of the document. At a stab, I’d guess 3 weeks for each document, assuming the original quality is fairly good.

    My experience is that management and non-tech-writers consistently under-estimate the amount of time it takes to produce a quality document. They simply don’t know.

    A suggestion: Now that you’ve had some good exposure to the documentation task, it would be a good time to make some estimates for the time required to complete the job. Base your estimates on the time you’ve spent so far (known) and add the time still required (estimate). Be ruthless about the time still required — don’t cut it short. And add a good section of time for reviews once you’re done.

    This will put you in good stead for the next task they might present, because you’d have a good basis to set their expectations.

    I guess the most important thing about extending your position there is whether you enjoy the work and the people. If those two things are good, then everything else kind of falls into place πŸ™‚

    In short: No, you’re not too slow. πŸ™‚

    Good luck, and let us know how it goes.

  6. Thank you so much. I really do love the work and appreciate the encouragement.

    The only other frustration I have is that I am female and find that the men I work under typically do not believe I understand technical material, despite my certification as an electronic technician and my education, which includes Physics and Calculus.

  7. You wrote this half a year ago, but I just read the post now . . .

    I am American and read somewhere that yes, that is why we changed the spelling and pronunciation of tidbits (I think during the Victorian age). In fact, it would be kind of embarrassing here to spell or pronounce it the original way.

  8. LOL. And now I’m beginning to get that feeling of discomfort every time I see the word too πŸ˜‰ Ah well, that’s the way language keeps changing.

  9. Susan Conaghan

    Can anyone recommend books for learning more about writing end-user documentation in an Agile environment? I already have Andreas Rueping’s book, but he says it is geared more towards product documentation. Thanks!

  10. Hallo Susan
    I don’t know of any books on writing end-user documentation in an agile environment. Scott Ambler has some really good pointers on Strategies for Agile Documentation. But they may be more general, like Andreas Rueping’s book.

    There is an “Agile” group on the Content Wrangler Community site. That may be a good place to ask other people if they know of any books:

    I hope that helps πŸ™‚

  11. Great minds think alike! I was toiling on several agile projects at Sun Microsystems when I had this epiphany that maybe someone else might be in the same boat, so I wrote a blog post on my experiences with agile teams:

    which I then shared on the Society for Technical Communications group on LinkedIn (and all of us shared your views as well).

  12. Hallo Joseph
    I’ve had a read of your blog post too — it’s very interesting reading. Heh, your last paragraph is hard-hitting but so true:
    “This effectively means that writers are no longer insulated from the software development and QA testing processes with a unique process just for product documentation. Writers will increasingly be asked (if not required) to participate as peers on the project team during agile software development, or else their jobs will (most likely) become redundant.”
    Cheers, Sarah

  13. Good points and comments. Not to blow my own horn (much) but a recent post plays with your thoughts very well. Tech writers as UX designers… who woulda thunk it?

    • Thanks Lee, and thank you for the link to your post. It’s an interesting read. I’ve dropped a comment there too. While I was there, I had a look around the other posts. Great blog!

  14. It was communicated very beautifully, Just the facts of everyday life of a technical writer, with smart humor. I liked it.

  15. I was a tech writer for 30 years. Maybe Gen ADHD can make the Agile paradigm work, but not me.

    Iteration junkies are programmed lab rats; read BF Skinner.

  1. Pingback: How to be an Agile Technical Writer with a cool acronym like XTW « just write click

  2. Pingback: A Glimpse into the World of Agile Technical Writing, a.k.a. Extreme Technical Writing (XTW) | I'd Rather Be Writing

  3. Pingback:   Weekly link roundup by Communications from DMN

  4. Pingback: Being a Technical Writer in Shanghai/China | Shanghai Tech Writer

  5. Pingback: What do I need to do to write Agile documentation? « Orion Spur

  6. Pingback: My trees and this blog are one year old « ffeathers — a technical writer’s blog

  7. Pingback: On The Fly (Part 2) « Outside Looking In

  8. Pingback: Collecting Agile Information « Empowering Learning

  9. Pingback: Technical Writers Get Agile | Technical Writer Jobs

  10. Pingback: Agile & Tech Comm: Can This Union Work? « Write Trends

  11. Pingback: Too long for twitter – Why I love my job! « I am a Tech Writer

  12. Pingback: TechComm Resources | INFORMAZE

  13. Pingback: The agile technical writer

  14. Pingback: Tech Docs as Agile Deliverables – Intercom

Leave a Reply

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

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

Facebook photo

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

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: