Sharing responsibilities in agile technical writing

Recently we shuffled responsibilities in our technical writing team. Andrew Lui and I now share responsibility for a number of products and documentation sets, instead of each person “owning” separate products.ย  I’m totally enjoying it, for a number of reasons. One of them is that Andrew is awesome! Another is that sharing responsibilities works really well in an agile environment, especially when it comes to crunch time.

One challenge a technical writer faces in an agile environment is that the development team splits into a number of sub-teams, each working on a different feature or bundle of features. The sub-teams work in parallel. As a result, all the features simultaneously reach the stage where we can start documenting them, and that’s usually quite close to release date. This can cause major stress for the technical writer and can require overtime work to get everything done in time.

If you’re lucky enough to have two or more technical writers around, it works well to share the responsibilities. This is not as obvious or easy as it sounds, but it’s well worth the effort.

Why isn’t it obvious or easy? There are a couple of reasons. Our instinct is to have each technical writer know a product and its documentation intimately. That’s especially true for technically complex products or documentation environments. It’s time consuming and demanding for each technical writer to know many products that well. Also, it’s seldom that a technical writer is assigned only one product. We usually “own” many. So if we have to share products, that increases the number of products for each technical writer and complicates our set of responsibilities even more.

Our particular case

Until a few weeks ago, I was responsible for a mixed bag of documentation sets:

  • Integration (the bits that hold our products together and allow them to talk to each other).
  • Crowd (a single sign-on and user management product).
  • Gadgets.
  • The “Dragons Lair” documents.
  • Various development frameworks such as the plugin framework and REST APIs (developer-focused documentation)
  • The three Atlassian IDE connectors (IDEA, Eclipse and Visual Studio)

Now Confluence wiki is on my list too, but Andrew is sharing the responsibilities for Confluence and the other bits. Confluence is one of our two biggest products, so it gets a big slice of the technical writing pie. I spend 50% of my time on the Confluence documentation and 50% on other stuff. Andrew also spends 50% of his time on Confluence and 50% on other stuff.

Sarah:

  • Confluence.
  • Crowd (a single sign-on and user management product).
  • Gadgets.
  • Various development frameworks such as the plugin framework and REST APIs (developer-focused documentation).

Andrew:

  • Confluence.
  • Integration (the bits that hold our products together and allow them to talk to each other).
  • The “Dragons Lair” documents.
  • The three Atlassian IDE connectors (IDEA, Eclipse and Visual Studio).

Why is it good?

Andrew and I both make sure we allocate the required percentage of time to each product, based on company and team priorities. But, and here’s the bit that works really well, each of us has the flexibility to shuffle the time allocations over an extended period.

For example: 50% of my time is allocated to the Confluence documentation, but that doesn’t mean I have to spend 50% of each and every day on Confluence. Nor even of each and every week.

As the agile schedule for a particular product approaches release date, both technical writers can spend 100% of their time on the features that are now ready to document. In effect, for that period of time, you have two writers on a single product instead of just the allocated one technical writer. Yaayyy, less stress and more achievable deadlines.

There’s even a reduced chance of having to cancel your leave if the product’s release date slips.๐Ÿ˜‰

As every technical writer knows, it’s awesome to have someone else to bounce ideas off. And to commiserate with when deadlines seem impossible.

Sharing responsibilities in agile technical writing

Why include a photo of a waterfall in a post about agile methodology? Heh. Anyway, this is a 16-foot high waterfall that appeared in our garden on the night of the record-breaking Sydney downpour last week. The entire family traipsed out at 11pm to have a look. By the time we took the photo, the force of the water had abated slightly. It was beautiful but a bit scary, especially as it was right next to the house. Quite a bit of the garden ended up at the bottom of the hill. Luckily the house didn’t!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 20 February 2010, in atlassian, technical writing and tagged , , , , , , , . Bookmark the permalink. 10 Comments.

  1. I’ve recently fallen into the role of Documentation Specialist at my office and started following a few blogs, including yours, to see how others do this type of thing. You talk a lot about wikis and other community ventures. Do you deliver paper manuals to your customers, or do you direct them to a website?

    • Hallo Ali
      Our primary publishing platform is the web-based documentation. It’s at this address:
      http://confluence.atlassian.com

      There are a few different documentation sets there, for different products, as well as a number of community discussion spaces.

      An example of a documentation set is the Crowd documentation at:
      http://confluence.atlassian.com/display/CROWD

      The above web-based documentation is on a wiki. We use the wiki as our authoring tool and our publishing tool, all in one platform. The wiki is called Confluence, and it also happens to be one of the products of the company.

      We do provide PDF snapshots of the documentation, for people who prefer paper-based documents or who cannot get outside a firewall. We produce the PDF files directly from the wiki, and make it available as an attachment on a wiki page. Here’s an example of a wiki page that offers PDF files (and other formats) for download:
      http://confluence.atlassian.com/display/ALLDOC/Crowd+Documentation+Directory

      I hope you enjoy the role you’ve fallen into.๐Ÿ˜‰

      Cheers, Sarah

  2. That’s an impressive waterfall! It sounds like the storm gave you an “agile” garden. I’m glad there was no serious damage.

  3. Sarah,
    thank you for giving consideration to the technical writer’s responsibilities. Really, I think it is a common practice of sharing the same product’s documentation between several tech writers instead of overloading the single writer.
    I used to work in a team of 8 tech writers. We own about 5 large products. We all describe all products together. We shared completed features and then described them concertedly.
    One of the main advantages of working with multiple products – you are not bored with the same product, you agilely switch between various subject fields and you keep your mind agile too๐Ÿ™‚

    • Hallo Katya

      It’s great to hear from you again! It’s also interesting to hear that your team shares the completed features over a number of products, rather than each tech writer having responsibility for particular products.

      We are a team of 5 people, but actually 4 because one is part-time and one is also the team lead. We cover approximately 15 products (it depends how you count them). So each person’s portfolio is fairly fragmented anyway.๐Ÿ™‚ Even so, it makes sense, as you say, for us to share a single product amongst more than one writer, although that makes our portfolios even more complex.

      Keeping your mind agile too I like that! Now we need to get everyone on rollerblades to keep our bodies agile too.๐Ÿ™‚

      Cheers
      Sarah

  4. I now work at a company that follows agile methodology closely (last time we spoke, over a year ago, I was still at a company that swarmed with project managers; actually, too many managers period). Switching to agile was a big adjustment, especially since documentation stories were not added to sprints to start off with (this has now changed, thankfully), but finally it all makes sense. And while things do get crazy busy towards the end of a sprint, at least I only have to catch up with three weeks of development๐Ÿ™‚

    • Hallo Rupert

      Congratulations, if that’s the right word, on the switch to agile. And definitely congrats on getting the documentation stories added to the sprints! Some of our development teams do that, others don’t.

      Also, there’s the question of whether the developers write some of the documentation. In our case and it seems almost always, there are too few tech writers to do all the work. In particular, it makes sense for the developers to focus on the API-related documentation. The bigger teams allocate time for this, especially towards the end of the release cycle (the last 2 sprints or so) when the product is in “hardening” phase.

      You raised another interesting point: the number of managers in your previous company. I wonder what the comparative ratio is of managers in waterfall as opposed to agile development shops! We started with very few managers, but have been increasing the number of managers, in proportion as well as in numerical terms, as the company grows.

      Cheers
      Sarah

  5. Hello!

    I just discovered your blog, and I’m glad I did. I’m working on the PhD in TC, and it is always educational and useful to read how people in job sites are handling real world issues.

    I know just a bit about Agile, so this was quite helpful. Thanks!

    gz

Leave a Reply

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

WordPress.com Logo

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

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

%d bloggers like this: