The agile technical writer II
In my previous 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.
Yeah that’s pretty much what we do as well. Another tip is to seat the tech writers with the development teams they are working with. Wouldn’t work in your place though.
Our teams rotate members after every release, and the tech writers do the same. You learn a lot of info from the conversations they have, and it means that we attend all the meetings, from the very first design.
The most daunting bit for me was the ‘iterative development’ bit, which I’ve called “trickling” the information as and when it is available and concrete enough to be used (more on that on my blog).
Gordon
26 January 2008 at 8:57 pm
I really enjoyed this post as well as part 1. So do you write all your documentation in the Atlassian Confluence wiki? If so, what do you do when someone asks you for a printout of everything in a manual format?
I also liked your comments about simplicity. In a product that is fairly sophisticated, what techniques do you use to keep it simple?
The whole paragraph on tidbits versus titbits was funny. I’ve been to England before (love the fish and chips with lemon juice), but I never heard anyone say titbits.
Do you use some kind of tracking tool like JIRA to keep track of what developers are coding and fixing?
Tom Johnson
20 February 2008 at 3:22 pm
Now I feel dumb. I just looked at your About Me page and see that you’re Australian, not English. Sorry about the fish and chips comment. I’ve never been to Sydney, but it must be a beautiful place.
Tom Johnson
20 February 2008 at 3:26 pm
Hallo Tom
No worries about the fish and chips thing
I’ve lived in England for a while. And I wasn’t born in Australia, though I have recently become comfortable with saying ‘no worries’!
We do write all our documentation in Confluence — well, except for the JIRA docs, which are in Apache Forrest at the moment but planned to convert ASAP. Confluence allows you to export a space (sort of a wiki within a wiki) to PDF format, which is handy for printing and offline use. You can also export a space to HTML and Confluence-specific XML. And you can export a page to PDF or Word format.
Yeah, keeping things simple is complicated
We use things like information-chunking — breaking subject-matter into small, logical chunks with highlights and headings to help people find their way. And we divide the material by audience e.g. a user guide and an administrator’s guide — so that we don’t tell people things they don’t need to know. And we try to de-obfuscate the developers’ language.
Hey, sounds like you’re a JIRA junky too. Yes, we use JIRA to keep track of what the devs are doing. We also attend the standups, and just generally keep all our antennae quivering.
Nice to get your comment!
ffeathers
21 February 2008 at 7:08 am
Thanks for your response. I didn’t realize that JIRA was an Atlassian product until just the other day. I’d seen the RSS capabilities, but hadn’t used them because, based on my experience with SharePoint 2007, I thought the feeds would be problematic in an authenticated, firewalled environment (esp. using a feedreader like Google Reader).
But yesterday I downloaded Feedreader and added feeds for the projects I’m on — wow. This is exactly what I’ve been missing in my attempt to stay in the loop of what’s going on in development. The tool is robust, but the feeds make it manageable.Thanks so much for the idea.
Tom Johnson
22 February 2008 at 6:39 am
[...] The agile technical writer An excellent write up of the typical processes followed by a technical writing team in an Agile environment. It’s good to read this kind of thing, as it matches roughly what we do so… we must be doing it right? [...]
one man writes » Recently Read
3 March 2008 at 9:51 pm
[...] agree whole heartedly. I think the Agile technical writer that Sarah Maddox describes is precisely the right person to be identifying keywords, get RSS watch lists configured, and read, [...]
Social Media Marketing Playbook - book review « just write click
19 March 2008 at 1:04 am
[...] as product manuals and online help. After that post, I came across The Agile Technical Writer and The Agile Technical Writer II by Susan Maddox. Based on her experiences working on agile projects. she came to the conclusion [...]
On The Fly (Part 2) « Outside Looking In
23 April 2009 at 9:00 am
The points that you made in this post are right on, especially the part about eating your own dog food. While I was working on an open source partnership at my last employer, the writing team was given the responsibility of performing a task analysis on the software that we would be (eventually) sharing with the rest of the community and write up common end user and administrator tasks to post on the project wiki. It was the team’s first taste of agile development and open source software, so it was important that we followed the policies and processes that the developer community already had in place for individual contributors.
joeaseo
23 April 2009 at 2:26 pm