ffeathers — a technical writer’s blog

I’ve been in San Francisco for the last few days, working in the Atlassian office here and meeting my SF colleagues. My visit has made me think about the pros and cons of long-distance communication, the technology we use to make it happen, and most of all just how good it is to meet people face to face.

Atlassian has offices in Sydney, where I’m based, and in Amsterdam, Japan and San Francisco. Sydney is the largest office, followed by San Francisco. We also have a team of developers in Poland, working on the Atlassian IDE Connectors for Eclipse and IntelliJ IDEA.

As a technical writer, I document some products that are developed in Sydney, some that are developed in  San Francisco and even some where the development team is in Poland. Recently we have also partnered with Tasktop (of Mylyn fame) to develop the Atlassian Eclipse Connector, a neat tool which lets developers work with their JIRA issues, Crucible code reviews and Bamboo builds directly in their development environment. I’m documenting the connector, which means I’m working with developers in Vancouver too!

Documenting from afar does work

So, long-distance communication is a must. And actually, it’s not bothersome. Many aspects are quite enjoyable, especially the technology. We have video conferencing that’s kind of fun, a wiki (Confluence) that works wonders, an issue tracker (JIRA) that works like a dream, Twitter, instant online chat… You name it, Atlassian tries it.

Sometimes I work from home, and the developers on the ground floor in Sydney don’t even realise I’m not at my desk on the first floor in Sydney So what difference do a few more thousand kilometres make?

But it’s just great to meet the people in meat space

I’ve discovered that many people look nothing like their TV images!

I document many of the development-focused products, like the Plugin Framework and the Shared Access Layer. The development teams for those are split between Sydney and SF. I’m also just starting the documention for the new Atlassian Gadgets and Dashboards. (See my earlier blog post.) Most of the development team is in SF. In the few days I’ve been here, I’ve created a new documentation space for Gadgets and Dashboards. The space is still just a skeleton, but I had the chance to review that skeleton while in the same room as the developers. Awesome.

• I joined the daily standups.
• I experienced the dynamics of the development team. All dev teams are different, as we technical writers know. We need to make sure we fit in as much as possible, to optimise the use of our time and the developers’ time. And to have fun.
• I met the people in the support, marketing and technical sales teams, who give so much input into and feedback on the documentation.
• I spoke to everyone else in the office, and verified that they actually look something like their avatars on the extranet, but only something like them.
• People took me round their favourite parts of the city, collected me at lunch time to sample a Mission Burrito, took me to some very up-market restaurants, and just showed me what a great place SF is.
• They laughed at my jokes.
  

And I was awake for the Eclipse Connector launch

To top it all, the new Eclipse Connector was launched on Monday, my first day in SF. It was useful to be in more-or-less the same time zone as the Tasktop development team in Vancouver and the people trying the connector for the first time at EclipseCon. I was able to respond quickly to requests for troubleshooting guides and FAQs, update the documentation and get the developers to review it on the fly. Fun and very productive.

Farewell fair San Francisco

And thank you to the Atlassian SFers, who gave me such a very warm welcome. This is a view of the city, taken from Twin Peaks just before sunset. The wide road going down the middle is Market Street:

Documenting from Afar

If you’d like to see more pictures of and words about my trip, drop by the Travelling Worm’s blog. He’s my bookmark and he keeps a fairly faithful chronicle of my travels

Tomorrow I’m heading off to Seattle (where it rains) for the WritersUA conference. I’m looking forward to meeting many other technical communicators there, including some that I know only from their blogs and tweets. More long-distance communication about to be converted to face-to-face meetings. See you there!

Long-distance or f2f?

I’m really happy with the long-distance communication. And I’m also very lucky that I had this chance to meet the SF teams face to face. I wonder how many technical writers are located some distance from their development teams. How about you, and does it work for you too?

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.

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:

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.