Monthly Archives: February 2010

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!

Did you ever buy anything just because of the writing on the package?

Have you ever bought something purely because of what’s written on the package?

Today I saw this small, medical-looking box in a store’s confectionery section:

Did you ever buy something just because of the writing?

It’s a bar of chocolate! It was expensive and I already had a couple of bars in my basket. Even so, I bought it. Why? Because I wanted to take the writing home with me. I was also a little curious about the chocolate inside the package. If the writing is so innovative, the product will probably be good too.

The chocolate is good, although I prefer milk to dark chocolate. But the point is that I bought it entirely because of the writing. That’s one up for us writers. Here’s what it says:

Confectioner only remedy
Keep out of reach of chocoholics

BOCHOX

active ingredient cocoa solids — 75%

For relief from the symptoms of wrinkles and crow’s feet.

Warning — May cause weight gain if used incorrectly.

Directions: Simply break off the desired dosage and consume. You should quickly be overcome by stress-relieving endorphins and no longer concerned in the slightest about your wrinkles.

Important: This packet is protected by a tamper-evident paper wrap. If seal has been broken suspect everyone. BOCHOX can be habit forming.

Store below 18° C.

NOT TO BE TAKEN seriously.

75% cocoa Swiss dark chocolate

It’s from Bloomsberry & Co, a New Zealand company that thinks chocolate. Their web site is a hoot too. Congratulations to Vanessa Kettelwell and all the Bloomsberrians for such awesome writing! And for the awful puns. ;)

How to write a blog post

Last week I wrote about getting started as a blogger. Now I’d like to tell you how I go about writing a blog post, in the hope that this will give you some tips on getting those blog posts written.

While I was writing these two posts, the DMN guys published an article on “How we blog“. Scott and Aaron write killer blog posts, so their article must be well worth a read. I haven’t read it yet (!) because I wanted to post mine first and then see how much we have in common. Here goes.

Quick tips

Here are some quick pointers. Let me know what you think of them or if I’ve left anything out.

  • Maintain a character in your blog, so that people can start seeing it as a friend. Blogging is a social activity. Be yourself! Otherwise it’s difficult to maintain a consistent persona and people will soon pick it up if you don’t sound real.
  • Give plenty of factual information, preferably hard-won. That’s what people value.
  • Feel free to intersperse bits of your personality. People like to know who you are.
  • Link to other people’s blogs. If your idea is an expansion of something someone else has written, include a mention of where you got the idea. If you’ve seen someone’s post about a related topic, link to it. The other bloggers appreciate this and will start linking back to you in return.
  • Be nice, positive and sincere. If you disagree with something, say so but be constructive. Some bloggers are successful by being horrid, but to make that work you have to be really good and have a curl on your forehead. I don’t like nastiness, manipulation or one-upmanship, so I wouldn’t recommend it.
  • Add structure to the content. Yes, even in a blog post. Put headings in the post itself. Split the information into easily-readable chunks. I’ve even chosen to have a bold, italicised introductory paragraph at the top of each post, reminiscent of newspaper articles.
  • Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read.
  • Make sure the title reflects the main story. This will attract readers and give you a good position in search results such as Google or Bing.

View every experience as fodder for your blog

Whenever something happens, think to yourself: “How does this fit into my blog?”

You can even write multiple blog posts as a result of a single experience or event. A while ago I wrote 4 posts resulting from one ‘Atlassian FedEx Day’, each with a different theme. Atlassian is the company I work for, and FedEx Day is a period of 24 hours when we all get silly and try to develop and deliver something within the space of 24 hours. The event itself was a lot of fun, and provided fodder for these posts:

  • A blog post on ffeathers, for people who are not Atlassians. This post introduces the concept of FedEx Day, tells the story of technical writers taking part in what is essentially a developer-focused activity, and shows lots of pictures.
  • My Atlassian FedEx delivery note, describing the purpose and results of my FedEx Day project. This is a more formal post. Everyone who takes part in FedEx is supposed to write one of these.
  • Another post on ffeathers, describing the software that I evaluated as part of the FedEx project. This software, the SHO tool for guided help, is of interest to technical writers so it was useful to write it up separately.
  • A post on the Atlassian company blog, describing the new SDK (software development kit) that I used. This post is aimed at developers, showing them that the SDK makes it easy for even a technical writer ;) to develop a plugin. There’s a fair bit of technical detail in the article. It’s also promotional, as suited to a company blog.

I could write another post about how to write 5 blog posts from one experience. ;)

What about actually writing the blog posts?

Here’s how it happens (mostly) for me.

Writing killer blog posts

How to write a blog post

Whenever an idea crosses my mind, I write myself a note.

I write the notes on paper, on the backs of envelopes, in emails, in an SMS message to myself, on a Post-it — you name it.

At some point the collection of notes reaches critical mass and I feel the urge to put it to bed in a blog post, before it explodes or I go mad.

So I sit down and start writing. My favourite time is on Saturdays after lunch, because that works for me and the family.

Sometimes the notes I have written are already fairly well crafted. Maybe I was on the bus and had time to write properly. Then I can just dump the words from the note directly into the post and tweak them a bit.

More often I end up with a disparate set of scribblings, in various forms and on various media. I read through them all just once. I want to bring them all to the top of my ever-bubbling pot of thoughts, but not to try to memorise exactly what I wrote.

Then I sit back and think, for a very short time (about 2 minutes), focusing on what I want to say in the post. That will be the main message, the theme and the story or hook.

Now I just start writing. For me, it’s better not to agonise too much about the actual words at this point, because that stunts the flow. I just write, as fast as I can, as if I were talking. If I can’t get the words out for a particular bit, then I write short half-sentences and a big row of “x”s, like this: xxxxxxxxxxxxxxxxxxxxxx. I move on to the next thought, so that I don’t lose the flow. Later, it’s pleasantly easy to find those “x”s (they stick out, as you can see) and either add the right words or just delete the whole sentence or paragraph because it has become irrelevant.

When I’ve done the initial braindump, I go through the scribbled notes again to see if I’ve covered them all. I don’t usually refer to them while doing the first braindump, because that also interrupts the flow. With great glee, I tear up or delete the notes that are already in the post. Usually, I find that I have covered them all. If I’ve missed one or two out, they often don’t fit in anyway. Then I either turf them or put them aside for another potential post. Tearing up or deleting the notes gives me as much pleasure as ticking off an item in a to do list!

At some point before publishing the post, I go and have a cup of coffee or a chocolate :) then come back to read the post again a while later. I try to put myself in the place of a reader who is seeing the post for the first time. What impression will they get, and is it the impression I want to give? Have I actually achieved a logical flow from paragraph to paragraph, or does part of the logical flow exist in my brain only? I fix up any typos, add bits and pieces, add tags, then publish the post.

Another moment of glee: I tweet “New post” and link to the post.

Does blogging take up a lot of time?

Oh yes! In my experience it takes on average 3 to 4 hours to write a blog post. I also spend an hour or so each day, reading other people’s blogs and responding to comments. Bus rides into work, plus a good mobile device, are great for this part.

Any more tips?

Let me know what I’ve left out. Now I’m going to meander over and read some other people’s ideas about how to write a blog post:

  • Scott and Aaron’s post on How they blog.
  • Seth’s post way back in 2006, a bit sparse on the “how to” but eminently elegant as always: How to write a blog post.
  • Seth’s post with more down-to-earth tips: Write like a blogger.
  • Neil Patel’s tips on engaging your readers in your blog: How to Write a Blog Post. Start reading from the top, then see what he has to say in the section titled “Hook your Readers”. It’s awesome.

See you on the blog rolls!

Following up on my presentation: I only part-way answered the question about how I start writing a post. We talked about writing yourself notes, whenever you have an idea. Put them on paper, on the backs of matchboxes ;) or in emails, via SMS, whatever. 

But then, what do I do when I actually sit down and start writing? Well, sometimes the note(s) I have written are already fairly well crafted, e.g. if I was on the bus and had time to write properly. So then I can just dump them into the post and hone them. But more often I end up with a disparate set of scribblings. In that case, I read through them all just once. Then I sit back and think, for just a very short time (about 2 minutes), focusing on what I want to say in the post -- that's the main message, the theme and the story/hook. 

Then I just start writing. It's better not to agonise too much, because that stunts the flow. I just write, as fast as I can, as if I were talking. If I can't get the words out for a particular bit, then I write short half-sentences and a big row of "x"s, like this: xxxxxxxxxxxxxxxxxxxxxx. And I just move on to the next thought, so that I don't lose the flow. Later, it's pleasantly easy to find those "x"s (they stick out) and either put in the words or just delete the whole thing because it has become irrelevant.

When I've done the initial braindump, I go through the scribbled notes to see if I've covered them all. I don't usually refer to them while doing the first braindump, because that also interrupts the flow. Usually, I find that I have covered them all. If I've missed one or two out, they often don't fit in anyway. Then I either turf them or put them aside for another potential post.

Then I go and have a cup of coffee (or, yes Andrew, a hot chocolate ;) ) and come back to read the post again a while later. At this reading, I try to put myself in the place of a reader who is seeing the post for the first time. What impression will they get, and is it the impression I want to give? Have I actually achieved a logical flow from paragraph to paragraph, or is part of the logical flow in my brain only? I fix up any typos, add bits and pieces, add tags, then publish the post. All in all, it takes 3 to 4 hours to produce a good post.

What do technical writers do?

It’s a question often asked of us: “What does a technical writer do?”

We tell people how to do technically complex things, mostly by writing instructions but also by drawing pictures and making movies.

Want to know more? I’m impressed by the write-up in the Occupational Outlook Handbook, 2010-11 Edition, from the US Bureau of Labor Statistics.

Thank you Tom Johnson for tweeting the link to the handbook today!

Follow

Get every new post delivered to your Inbox.

Join 1,446 other followers

%d bloggers like this: