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.
Posted on 26 January 2008, in technical writing and tagged agile, agile manifesto, agile programming, agile technical writing, extreme programming, technical writing, XP, XTW. Bookmark the permalink. 17 Comments.
ffeathers 
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).
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?
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.
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!
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.
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.
Our company adopted Agile (XP) about a year ago, and we’re still trying to work out the kinks. One of the issues we’re having is what a good ratio of developers:QA:tech writers:PMs would be for each team. I was wondering if you could share that information about your company, to help me get some perspective.
Hallo Cory
It’s an interesting question, and the topic of much ongoing debate at work as well as on various blogs.
For the ratio of technical writers, I think we’ve got it about right at work at the moment. We have four full-time tech writers and one other who works two days a week. That gives us a ratio of approximately 20+ engineers per tech writer. But that number is perhaps not meaningful or particularly applicable to other organisations. Wee have a number of unique products and some mashups of those products too, all requiring documentation. Some of the documentation work comes from plugin developers as well, so the ratio is in constant flux. We could easily absorb another tech writer 😉 but we’re not totally overwhelmed with work that can’t be done.
I think every environment is different in this respect, particularly in the agile world. I did ask the question in a blog post a while back, though not specifically about agile environments. The responses were interesting too: Ratio of developers to technical writers.
For QA and PMs, we’re still getting the balance right. Our policy has been to start small then expand and see how much value the new roles are adding. We have four QA people, and I think most people agree we need more. We have a product manager per major product, and are in the process of expanding that team too.
I guess it’s an agile process, just as development itself, constantly re-assessing the structure of the company and putting people into the roles that they enjoy, that they do well and that the company needs.
Cheers
Sarah
Good to know about agile tech writing! Has heard about agile programming only. It’s so collaborative as that the developers can participate, and customers too! But what I want to know is, is this possible for product documentation where content can be changed by the users themselves?
And, to implement such a system/environment at your work place, what preparations are to be taken?
Well, no doubt not all agile environments are created equal. “Agile,” is sometimes code for pulling it out of your ass at a moment’s notice and acting like you’re so damned hip that no one will call you on it.
Hallo Beekins
It sounds as if you’ve had a nasty experience of an agile shop recently. I guess in this day and age it would be difficult to avoid being called on such bad practices, though, especially with blogs and tweets and all the other channels out there right now. The principles behind the Agile Manifesto put the customer firmly at top priority: “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.” Any agile shop, or other development company, is bound to make mistakes some time, but they should respond quickly to put things right. I do hope your experience improves!
thank you so much for your posts (I and II),
and I like your language)
We are just jumped into Agile, and the company is taking it seriously. Each writer is assigned to a single project (which means we have some scrum teams with no writer – scary thought!). As part of a self-organizing team where each team member should be willing and able to jump into whatever needs to be done to complete PBIs for the sprint, this means we are often roped into other roles like development and testing; on my team, which has no assigned tester, this means I often feel like I’m 70% tester, 20% consultant, and 10% writer. Is anyone else in this boat, where you feel a loss of our speciality? How are you dealing with it?
Hallo Schultza
That’s a very good point. In the case of our team, we found that this was very much the case during the first year or so, but recently the company has hired more “specialists”: QA engineers, UI designers, and tech writers too. These days, we are able to spend more time on the user assistance side of things, which may include things like the UI text and in-app help as well as the documentation itself. We don’t find ourselves spending as much time on QA as in the early days.
I guess one way to tackle the problem would be to make sure that the documentation tasks are recognised as part of the “definition of done”. That would mean that the sprint cannot be declared complete until the documentation is complete too. Since you’re the best person to do the documentation, you may be able to spend more time on it if necessary.
Cheers, Sarah
Pingback: one man writes » Recently Read
Pingback: Social Media Marketing Playbook - book review « just write click
Pingback: On The Fly (Part 2) « Outside Looking In