Documenting the Atlassian IDE Plugin on a wiki

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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 12 April 2008, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , . Bookmark the permalink. 5 Comments.

  1. Interesting post. Just goes to show you that you really can use a wiki (along with a good strategy and structure) for documentation. And do the job quickly.

    One question: what did you use to generate the PDF output? A Confluence plugin that uses FOP? Or some other magic?

  2. Hiya Scott, Thanks for your comment. About the PDF output — Confluence has a “space export” option that lets you generate a PDF version of the whole documentation space. You can also generate HTML and XML outputs of the space, and Microsoft Word outputs of a single page.

  3. Yes. The sun shines in Poland.😉
    I bet that even more than in Sydney in June or July.
    Come and see for yourself.

  4. Nice job on the documentation, Sarah!

  1. Pingback:   Weekly link roundup by Communications from DMN

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: