Community authors and our technical documentation

Shiver me timbers! We’ve decided to throw our official documentation open to updating by outsiders.

This is a big thing, for me and for the other technical writers at Atlassian. It’s also a big thing for many Atlassians and the community developers who work on the code and plugins for the Atlassian applications.

From my point of view as a technical writer and wiki hugger, it’s awesome to be making even greater use of the fact that our documentation is on a wiki.

And from my point of view as a technical writer and perfectionist… Well, “eek” springs to mind😉

How did it happen?

Our technical documentation is housed and authored on a Confluence wiki. Up til now, in general only Atlassian staff have been granted ‘update’ permissions on the documentation spaces. We’ve been thinking about granting wider update acccess for quite a while. We pride ourselves on being an open company. We all acknowledge that our community developers, partners and other “ecosystem” inhabitants are awesome and can add a lot of value to the documentation. But there was a lot of thinking and organising to do before we could make it happen.

Then at an Atlassian geek gathering, the community developers stated their case fairly strongly. A “community developer” is someone who writes plugins and extensions to our products, but is not an Atlassian staff member. They often have hints and tips that would be useful to other developers. They can post comments to the forums or add comments to the documentation pages, or blog about it on their own blogs. But that’s not the same as having access to the structured, version-controlled, official technical documentation. They may even find something that needs correction in the documentation. No, never! What, never? Hardly ever😉

Awesome! They recognise the value of our documentation. And they’re right.

So we dove into it with gusto. There were two big things to sort out:

  • Intellectual property.
  • The impact on the Atlassian technical writers of monitoring the additional updates for correctness etc.

At first, we had an idealistic view: Let’s just throw the documentation open for editing by interested parties, without asking them to sign any agreements. We didn’t want to deter any would-be contributors by forcing them through an unwieldy signup process. But we soon realised that we need to protect both ourselves and the contributors from unforeseen events and possible malicious interference. So we’ve created an Atlassian Contributor License Agreement, based on the Apache Contributor License Agreement.

This was a really interesting exercise. Jason Sprague from Sparke Helmore Lawyers advised us on the wording and ramifications. Thank you for all the help and advice, Jason!

What does this mean for the technical writers?

As one of the Atlassian technical writers, I’m excited, delighted and just a bit daunted by this turn of events.

  • Will we be swamped by updates? The technical writers have RSS feeds on all the documentation spaces, so that we can see who has done what to our precious words😉 Now there will be even more updates to keep track of.
  • Thinking about correctness and accuracy, we’ll often have to consult the development team to verify the updates made by community developers.
  • And of course, what about consistency of style and spelling? We’ve written a mini style guide. Will it work? Too much, and no-one will read it.
    Too little, and we’ll turn into full-time proof-readers.Community authors

While we’re talking about spelling…

Here’s a bit of light relief. Spelling variants are an endless source of interest to technical writers. Debates may get heated or hilarious, and none more so than the tussles between Australian and US spelling proponents. Atlassian is an Ozzie company and our products use Ozzie spelling in their screens, messages, etc. Many of our customers are in the States or other places in the world…

The Atlassian JIRA team recently had a “sad day” when “Australia’s cultural imperialism took another step backwards” and they grudgingly included a US language pack for JIRA. Here’s the blog post.

Igor Minar tells me that technical writers in the US get all “wrinkly” when they see the Ozzie spelling in the Confluence user interface:

Community authors
The tweets are here: Igor, Sarah, Igor. LOL, thanks Igor!

Getting back to the community authors

The awesome side of opening up our documentation far outweighs the worries:

  • We’ll be getting up-to-date technical information direct from the developers, often keyed in as they code. This is especially valuable for the more technical documentation, such as the Atlassian Plugin Framework and soon the Atlassian Gadgets too.
  • We’re using the Confluence wiki at its best — updates by many, monitoring via RSS feeds, bottlenecks unplugged.
  • I’m hoping that the new contributors will enjoy updating the documentation and feel more ownership of it and of the applications too. Anne Gentle has an interesting related post about User-generated content versus community-generated content. And one of our community authors has already blogged about the opportunity to contribute to the Atlassian documentation: A truly open company. Wow, that was fast🙂

A trial period first

Just in case the worries get the upper hand over the awesomeness, we have decided to run a trial for three months. Then we’ll take a look at the extra workload, the feedback from the contributors, the quality of the updates, and so on.

I’m so hoping for a successful trial with lots of awesome updates!

CC-by

While we were busy with IP-related things, we sorted out the copyright on our documentation too. We’ve stamped the documentation with a Creative Commons Attribution licence. To the technical writers, this is not such a big change. It’s more like a confirmation of our unofficial policy. But it’s pretty cool to have it in black and white, and with such an attractive CC-by logo too!

Stamina for more?

If you have a yen for the infamous “more details” (that’s a technical writer insider joke, folks😉 ) take a look at the post on the Atlassian News blog.

If you’re interesting in contributing to the Atlassian documentation, drop us a line.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 7 March 2009, in atlassian, Confluence, open standards, technical writing, wiki and tagged , , , , , , , , , , , . Bookmark the permalink. 9 Comments.

  1. If you can get users to actually contribute, then I think this move might be a good one. As I always say (and forgive me if you’ve heard this before), the people actually using what we document are dong so in ways that we can’t imagine in our little development/documentation silos. Absorbing that knowledge can only help improve the documentation.

  2. Hallo Scott,

    That’s a great point about people using the products in ways that we haven’t thought of! Especially with applications that allow extension via plugins and APIs, people are doing awesome things to make the product do what they want.

    I guess now we’re allowing similar extension of the documentation. I wonder what previously unthought-of magic will start appearing in the docs🙂

    Cheers
    Sarah

  3. This is so timely. There’s been a lively discussion over at austechwriters about new delivery media and the future of tech writing. Many people think wikis are not suitable for official technical docs. Confluence was raised as a counter-example:

    http://www.freelists.org/post/austechwriter/atw-Re-Should-we-give-the-users-what-they-want,34

    People also think that a company would have to be crazy-brave to open their official docs to user-generated content. And now you’re going to try it… It will be so interesting to see how it turns out–good luck.

  4. Hallo Stuart

    Thank you for the encouragement🙂 and also for that link to a really interesting discussion.

    I’d agree that there are cons as well as pros when using a wiki for technical documentation. Like all tools, it fits certain types of documentation and certain types of companies, development methodologies and audiences. For us, in an agile environment where the products are for the most part web applications themselves, it’s an ideal tool.

    There are some improvements to be made in our Confluence wiki software, to make technical writing easier — but we have a voice there too, in putting our ideas and requirements to the development teams.

    As someone says in the post you linked to: Exciting times!

    Cheers, Sarah

  5. Sarah,

    A very interesting look at the evolution of Atlassian’s thinking about content “ownership.” The days of command and control are long behind us, replaced by collaboration on all fronts, thanks to the Internet and all it’s glorious social media offspring: chatrooms, discussion forums, wikis, and even this blog!

    Tom Roux
    Editor-at-Large
    The Business Insider Blog (www.timrosablog.com)

  6. Hallo Tom
    That’s a good point, about all the social media types. The whole idea of documentation existing in just one central place is becoming a bit dubious😉

    With our technical documentation, we plan to keep a fairly tight rein on it, in that the technical writers are monitoring all updates via RSS feeds or space watches. We need to keep the balance between collaboration on the one hand, and a quality product for our readers/customers on the other.

    But as you’ve implied, the blogs and forums and all that other stuff are part of the big picture too, even part of the technical documentation itself. Great comment!

    Cheers
    Sarah

  7. What a great post! We are also just starting to think about how we might open up our documentation and tap the community of knowledge. It is challenging when some parts of the documentation are considered “warranty” and when mistakes could cost both customers and the company a lot in terms of unnecessary support calls, etc. Finding the balance point will be important.

  8. Hallo Tamara,
    Wow, it will be interesting to hear of your experiences too. You’ve hit the nail on the head by saying the balance point is important. On the one hand, you have all these community developers and authors with so much skill and knowledge. But on the other hand, they’re working within their own particular environment and their information may not be widely applicable. They’re not necessarily technical communicators, so the structure of the information may not be ideal. Even though it’s not incorrect, it may not be entirely correct😉 So the monitoring and review by the technical writers and internal development staff is a critical part of the process.

    Good luck with your investigations into opening up your documentation too!
    Cheers, Sarah

  9. Been a big fan of your doc for some time as you know, in particular the methodology approaches for corporate advantages with hugely increased web visibility, seo benefits, single-sourcing, collaborating content directly with the source (engineers) for streamlined reviews, etc… and last week got a call from a future client also interested in this mode. It is catching on, but like all new things, takes forever to catch on. The passion for the path is fire, but only with more and more reference examples on the web, with the fire grow perhaps. I don’t know.

    Love your “Shiver Me Timbers” comment – I can certainly identify with that. This will indeed be an interesting yet well controlled expirament for you all – good luck with that.

    On the American spelling stuff, yeah – it’s an issue over here in the US, and TWs are particularly picky of course. The US can be arrogant on thinking our spelling and ways are the only ways, despite the charm of British spelling (how viewed here). If a consolation, the charm of your accent will always trump an American’s even from our side.😉 We simply like them, alot. My perspective anyways.

    Again good luck in coming months…

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: