ffeathers — a technical writer’s blog

In my last post, I promised a braindump of the things our team has learned over the last months as technical writers in an agile environment. So here goes.

First of all, the agile turtle has had a makeover:

Thanks to Ryan, who was totally mortified at my previous clipart mix-and-mashup.

So, what are the tips and techniques? They’re not rocket science, and they’re not so very different from what tech writers do every day even in non-agile environments. The main thing is an eagerness and enjoyment of going with the flow.

Stay on the hop and she’ll be right, mate.

Off on a tangent: I tried some chocolate beer last night. It was ~interesting. But that’s not the kind of hop I’m talking about here.

OK, let’s go:

• Attend the development team standups (short meetings held standing up). This way, you get advance notice of new features, patch releases and changing deadlines.
• Let the development teams know what you’re working on. Your work will dovetail with theirs quite neatly. I often find that I’m tackling a problem area in the documents (e.g. LDAP integration) at the same time as the developers are completing enhancement requests and the support team are weathering a storm of problems around the same topic.
• Keep your contributions short at the standups. It’s a bit of a balancing act: some developers think you’re wasting their time. That’s not unique to the agile environment though. Not everyone is in on the secret that documentation is actually at the centre of the universe
• Make sure that the documentation is seen as part of the product, and that your development timeline is factored into the product release. Again, this is tricky — I’ve worked in places where this is seen as merely a nice-to-have.
• 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
• Think like an engineer. When documenting a new feature, evaluate the end-user’s experience while writing the ‘how to’ stuff. Does it actually work for them? Remember that your feedback is valuable. Often, you are the first end-user-type to use the software, and you (or your documents) frequently have more of a big-picture and procedure-oriented view than the developer who wrote the code.
• Apply the principle of iterative development to the documentation as well as to the software. Contribute to the QA and testing process, and be ready to adapt the documents to reflect any resulting code changes.
• 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.
• Seek even more input! Attend impromptu and scheduled training sessions. Attend the planning session which usually happens at the first iteration in each major release cycle. Keep your eyes, ears and antennae tuned for any other sources of information.
• 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.
• Monitor the bug-reports and enhancement requests coming in for the product. Take note of any that will affect the documentation.

And here are two brand new techniques which our team has just begun trying out:

• Swaparoo: In our team, each tech writer looks after three products. To get some cross-product knowledge going, we’ve started swapping tasks. One of us might announce in our daily standup that she is available for a swaparoo. The others will look for a suitable task that’s currently assigned to them. It might be a new feature for the next release or a meaty maintenance issue. And then the two writers will work together to get the job done. This is very like the ‘pairing’ that agile developers do. We just like the word ’swaparoo’ better.
• Code reviews: Get yourself included in the code reviews for major updates. Our company uses Crucible, a tool which allows engineers to embed their code reviews into the code and share the review comments with any number of people. The developer can assign a group of people to take part in the review. The tech writer can pick up some useful tips here too, just by watching the review comments whizz by.

And then, find some time to do a bit of writing.