Blog Archives

Badges for Twitter tips and thanks to technical writers

It’s recently struck me again: There is so much creativity, generosity and enthusiasm in the technical writing community! A while ago, I let people know that I was kicking off a project called Tips via Twitter. Many technical writers commented and tweeted their encouragement and ideas. Now we’ve just started a Twitter tips stream for another of our products, and designed badges that tweeters can display on their blogs.

The badges are oh so cute. Vijayendra Darode came up with the idea and posted a comment on my earlier blog post:

To encourage users to tweet tips, I would consider giving them a badge of honour which they can proudly display on their blogs or any social networking site. A badge which says “I share my Tips via Twitter. Do you?” or something similar.

Thank you so much Jay! Here’s what the badges look like:

Badges for Twitter tips and thanks to tech writers Badges for Twitter tips and thanks to tech writers

(If you want one for your blog, grab the HTML from my Atlassian blog post.)

Highlighting the fact that people can contribute to the documentation

Larry Kunz had another great idea, that we should make the community aspects of our documentation more visible. So I’ve been creating pages called “Contributing to the xxx documentation”, where “xxx” is the product name. For example, here’s the page for our JIRA bug tracker: Contributing to the JIRA documentation, and for the Confluence wiki: Contributing to the Confluence documentation.

The “Tips via Twitter” pages are now children of those pages, and so are the “Tips of the Trade” pages, where we link out to “how to” blog posts by our customers and community.

What’s more, we now have a shiny new button in the page footers, directing people to the page about contributing to the documentation:

Badges for Twitter tips and thanks to technical writers

Thank you to the technical writing community

Innovation, passion and generosity are alive and well amongst technical writers. Thank you everyone! I’ve also added a paragraph in the Atlassian blog post, letting people know that the technical writing community rocks!

Technical writers hold an innovation sprint

At Atlassian, where I work, the pace is fast and furious. Always. It’s fun, invigorating, challenging, and I wouldn’t have it any other way. But there’s just never a breathing space. So when do we find the time to think about innovative techniques or procedures in our technical writing and documentation? The answer to that one is, all the time. If we have an idea, we’re encouraged to blog about it and see what people think. OK, cool, now we have some ideas. How do we find the time to put them into practice? That’s more difficult.

A couple of weeks ago we held an “innovation sprint”. This is a new idea, designed to tackle exactly the problem of finding that time to try out our innovative ideas. It worked and it was a lot of fun. Chocolate was of course inevitable. We wore some funny hats. And we made great progress on our innovation projects. So I thought I’d tell you about it.

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

What’s an innovation sprint?

Well, it’s a new idea. I haven’t heard of anyone else doing it, but if they do then their innovation sprints may have a different format. Here’s how we ran ours.

Planning: To prepare for the innovation sprint, we set a date and decided what each person would be doing during the sprint.

To take a step back, let me tell you about our “innovation register” and “innovation deputy” role. We already have an innovation register where we collect any ideas coming from us or from anyone else. The idea has to be something new. It can be procedural or part of the documentation itself. We also have a designated innovation deputy, a team member who is keen on innovation and who brings in new ideas, coordinates activities and makes sure everyone has an innovation project to tackle. The idea of an innovation deputy is also new, and I’ve filled the role for the last 6 months. The team lead and innovation deputy regularly discuss the new ideas with the rest of the team, and together we all decide which items are feasible and who would like to tackle what. So we made use of this register for our innovation sprint.

The sprint: We allocated a day for the innovation sprint itself. Yes, a whole day. Luxury! On that day, the technical writers planned to do nothing except work on an innovative idea for our documentation. Preferably, the project should be something that’s agreed upon beforehand with the rest of the team, and preferably it should be an item from the innovation register.

Demo: We also allocated an hour a couple of days later, where each of us demonstrated what we had managed to achieve during the sprint.

Hint: Schedule the demo session for a couple of days after the sprint. Even better, put a weekend between. That way, people have time to tidy up what they did and compile their demo. In our case, two of us were so fired up by the sprint, which happened on a Friday, that we worked over the weekend to finalise our project and have something to show. Cheating? Nah! Because it’s all about the ideas and the feeling good, not about the time.

Why the funny hats?

We wanted a tactful way of letting people know that the technical writers were otherwise engaged for a day. It worked. And it was funny. Here’s a typical conversation I had a few times with people coming into the office that day:

Newcomer: Is it tech writer hat day?
Me: No, we’re doing an innovation sprint today. The hats are a subtle way of saying, “Keep off, no doc requests today.”
Newcomer: Oh, that’s your thinking hat!

What did we get done?

A lot!

Giles continued working on his automated documentation publishing tool. This is a long-term project, fondly known as the “releaserator”, aiming to automate some of the procedures the technical writers follow when publishing documentation updates on release day.  We write and publish our documentation on Confluence wiki. There are some things the wiki does not yet do, from the point of view of publishing technical documentation. Giles is developing a plugin for Confluence to fill some of the gaps. The releaserator now has an awesome prototype of the configuration screen it will need in the Confluence space administration section. As a bonus, Giles is now a Velocity fundi. (We’re not sure that he ever wanted that distinction, but hey, who’s complaining.) Here’s the prototype of the configuration screen (click the image to see a larger version):

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

Rosie continued with her flowchart visualisation project. The aim is to use Gliffy to display a hyperlinked diagram at the top of each page in a procedural document. The diagram has a box for each stage in the procedure. The step you’re currently working on is highlighted and the boxes are hyperlinked so that you can move easily from one step to another. This project is not yet visible on any published pages. Here’s a screenshot of the prototype:

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

Andrew started work on a shiny new conceptual overview of Confluence wiki, also using Gliffy. Although still a work in progress, this page will soon become an awesome and useful document for our customers. It consists of a couple of diagrams showing the conceptual components of Confluence, such as the dashboard, spaces, pages, comments and labels. Each component is hyperlinked to the documentation page that describes that component.

I finalised my project called “Tips via Twitter”. The aim is to encourage people to tweet hints and tips about our products. What’s more, we publish a live Twitter stream on a page in the documentation. Tips via Twitter is now live for one of the Atlassian products, Confluence wiki. After one month’s trial, ending in mid-July, we will decide whether to roll out Twitter tips for another product called JIRA. I wrote about this project in an earlier blog post: Hints and Tips via Twitter.

What about the chocolate?

Ed, our team leader (not pictured above), went on a quest throughout Sydney to find some unique chocolates. Since the Atlassian technical writers are all such chocolate connoisseurs, it’s hard to find something new. But Ed came up trumps with these chocolates from Adriano Zumbo Chocolat Café in Balmain:

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

The flavours were, well, unique:

  • Strawberry and balsamic (front right, the smooth square one with silver dust on them). Pow! Taste sensation. At first powerfully sour. Then a bit overwhelming, but suddenly melting away to nothing at all. This was my favourite.
  • Chilli (front left, the dark, igloo-shaped one). Nothing special, actually.
  • Lemon (middle right, the corrugated one). Sour. Nice, but not as dramatic as the strawberry ones.
  • Dark chocolate honeycomb (middle left, the irregularly shaped one). Tasty. More or less as you’d expect, and nice and fresh.
  • Coconut, coriander and cardamom (at the back, the coconut cluster). Good. Again, more or less a conventional coconut cluster, but nice and fresh.

The innovation sprint was good. We plan to hold them regularly from now on.

%d bloggers like this: