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.
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.
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:
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!
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.
Posted on 7 March 2009, in atlassian, Confluence, open standards, technical writing, wiki and tagged atlassian, Confluence, documentation, JIRA, language, plugin, plugins, technical documentation, technical writing, wiki, wikis, writing. Bookmark the permalink. 9 Comments.