ffeathers — a technical writer’s blog

It’s a great week for technical documentation on a wiki. Confluence 2.8 is out and it includes manual page ordering. The technical writers at Atlassian have been vocal lobbyists for this feature for quite a while. I’m sure that many people who voted for the feature are technical writers too.

When you’re writing a documentation set, the sequence of the pages and chapters is very meaningful. It’s nice… well, many would argue that it’s essential to be able to define a logical page order rather than being stuck with an alphabetical order. Up to now in Confluence, we’ve worked around the problem by manually adding chapter numbers and page numbers, like “1. Introduction”, “2. Installation Guide”, “2.1 System Requirements”, and so on. Now take a look at point 2 in the Confluence 2.8 Release Notes. We can just drag and drop the pages and chapters where we want them. They stay there and the new order is reflected in the PDF outputs and hierarchical page-tree views. Magic.

Here’s the page-ordering feature request on our JIRA issue tracker — it has 174 votes and 87 watchers (i.e. people who want automatic notification of any developments on the issue). The JIRA voting system certainly helped to get this particular feature into Confluence. It was a non-trivial change, and took a fair bit of effort from the development team.

A big hug for the Confluence team on behalf of technical writers everywhere ♥

Other Atlassians think the new version of the wiki is awesome too. See what Fag on FOSS has to say. There were a number of people involved in getting the release out there, and it’s cool that we’re all so pleased with it.

How are my trees doing?

It’s been a while since I ventured to the top of the garden to check up on my two trees. Some of you many have seen my first post about the trees, way back in August last year, when I planted the trees. Now they’ve been in the ground for eight months. They’re about the same age as this blog.

The Old Man Banksia is now 98cm high, grown from 17cm at planting:

The Prickly Paperbark has shot up to 172cm, from 40cm at planting. Its trunk is about the girth of my finger. As you can see, the garden around the Paperbark is a bit of a jungle, but the tree is holding its own:

Things came together at work this week and we decided to release the new Atlassian IDE Plugin a month early. The software was ready, but what about the documentation? Well, yes of course! But it did take a bit of doing.

Luxury — it’s a technical writer’s dream. I’ve just written an entirely new set of documentation, for a brand new Atlassian product called the Atlassian IDE Plugin. If you already use one of the other Atlassian products, the IDE plugin lets you integrate information from those products into your integrated development environment. The plugin pulls in information from JIRA bug tracker, Crucible code review tool and Bamboo build manager.

This was an interesting project from a technical writer’s point of view, for a number of reasons:

• The developers have joined the company fairly recently, and they’re Polish. They assure us that this is no cause for panic
• I am in Sydney, Australia. The developers are in Gdansk, Poland. Is that just about as far apart as you can get?
• We wrote the bulk of the documentation together, in two days.
• They’re asleep while I’m awake.
• They speak a different language.

We’re using a Confluence wiki for our technical documentation. The wiki really helped us here. First I set up the framework, defined the topics and wrote the introductory stuff. When the decision came to release the product, the developers filled in the technical bits while I was asleep and the sun was shining in Poland.  (Does the sun shine in Poland?) Then I came back online and finished it all off. We tweaked a few more words during product management reviews over the next 24 hours, and Bob’s your uncle.

Scott remarks that structure is all-important when you’re writing documentation on a wiki. He’s so right! We have a well-defined and fairly standard structure for our online documentation. I had already set this up for the new product’s documentation space. So when the rush was on, I could just copy the framework from other documents, like the release notes and user guide topics, and adapt it to the new product. In this respect, writing on a wiki is no different to any other form. Structure and consistency are gold.

How did it go? Very well. Here is the resulting documentation — what do you think? It was satisfying to sit down early one morning, get in the zone, and stand up ten hours later with the first cut well and truly in place. The interaction-from-afar with the Polish development team was fun too. And we’re all proud of the result

Next comes… maintaining and perfecting the documentation and the plugin itself. (Yeah, yeah, I know a lot of people would swap the sequence there. But I’m a technical writer, remember.) We’re looking forward to the comments that customers and other people will drop on the wiki, letting us know how we’re doing.