Boy, were those two completely different worlds of documentation!  In the one setting, we had team fully dedicated to managing documentation – ENTIRELY!  We were documentation specialists.  In the other setting, documentation was either needed or not needed.  It wasn’t someone’s “job” to document, rather, the documentation was a byproduct of the development or business contract.

Of course, I didn’t mind the second setting in the least.  Even though I have a technical writing degree, I completely get the logic behind the theory that documentation is simply a means of communication, and a pretty lousy one at that.

Here’s why:

1. It’s expensive.
2. It’s high-maintenance.
3. It serves no real purpose.
4. The wrong people write it.
5. The right people ignore it.

Traditional documentation can’t keep up with you.  It can’t follow you.  You can’t ask it, “do you get what I’m saying?”  It’s a static, physical object that someone – a live person – must update constantly.  And that takes time.  And time costs money.  Lots of it.  And what’s worse, if you print tons of copies (even worse, in color!) it’s wasteful and bad for the environment.  I abhor traditional documentation (which is essentially blasphemy for a technical writer to say, right?).

Scott Ambler wrote a great piece on this subject a handful of years ago, and you can read it here.  It goes into much more detail (and commentary) than I will here, but it is an excellent resource for any technical writer or manager looking to adopt agile development methods.

In an agile development environment, communication is king.  The focus is taken off of a certain document and instead is placed back onto the what – what does this system do and what do its users do with it?  Business analysts in this setting need to understand modeling and need to have a much higher technical aptitude than a traditional tech writer.  They also need to understand how to write acceptance tests, because these become the building blocks for development.

So are tech writers obsolete in this new world of development?  Sadly, most probably are.  Business clients are being wooed and romanced by the show and tell model – rather than producing endless revisions of updated “documentation” that supposedly reflects what’s actually being developed, agile developers are releasing more frequent builds of in-progress projects.  Business clients can then provide feedback, and changes can be made and released in the next build.

Of course, there are serious pitfalls (scope creep, out of control change requests, etc.) with that process, and this is where the old tech writer can grow into a more functional role in an agile setting.

• If a tech writer can take on business analysis skills, these new BA types can interface with clients and sales engineers (and hopefully, keep them both in check).
• The tech writer/BA can be attractive to the business client, because this type of BA can produce better documentation, which in the end is still always required by the business client (clients need to show documentation to their stakeholders, product marketing managers, etc).
• The tech writer/BA will also be useful to the agile developer (even if she or he doesn’t realize it) by communicating necessary changes (bugs) rather than an endless stream of change requests.  Ultimately, good developers would rather not be face-to-face with business clients.  The two do not share a common language nor a common goal, so it’s best if there is someone in between who can really bridge the gap between those two worlds.

So, in my opinion, yes, technical writing as a function within a development cycle is out of style and organizations trying to adopt agile techniques will need to let it go.  However, technical writers need not jump ship altogether.  Instead, making a transition from king or queen of documentation to king or queen of communication would be a great strategy.

© 2010, Tia Peterson. All rights reserved. This text may be reproduced with permission. Please contact tia@tiadpeterson.com to request permission to reuse this content. Thank you!