New Jira 5.0 tutorials from the Atlassian doc sprint

The Atlassian technical writers and thirteen developers recently combined forces in a doc sprint. The aim? To develop plugin tutorials that will help people use the upcoming Jira 5.0 Java APIs. The result is eleven shiny new tutorials and plenty of updates to existing pages. The indomitable doc sprinters were based in Sydney, San Francisco and Gdansk. We got together in chat rooms, in video conferences and on the wiki.

New Jira 5.0 tutorials from the Atlassian doc sprint

What is a doc sprint?

A doc sprint is an event in which people get together to develop a specific set of documentation. This sprint took two days, and we needed every minute of them.

Credits: Thank you to Nick Mason for the monochrome photos, adding a touch of drama to an already classy event. Paul Watson and I took the colour shots. Check out the rest of the doc sprint photos on Flickr.

The tutorials we developed during the doc sprint

Feedback from plugin developers indicated that our existing tutorials are either very simple or very complex. We didn’t have enough in between those two extremes. Now we have eleven new tutorials, positioned nicely between “hello world” and “build a battleship”.

The tutorials and documents are all on Atlassian Developers, our one-stop-shop for the Atlassian development community. Drop in to see how we have revitalised the developer documentation, added tools and reference documentation, and more.

New Jira 5.0 tutorials from the Atlassian doc sprintNew Jira 5 tutorials:

Two new tutorials that are useful for all plugin developers, not just Jira:

New Jira 5.0 tutorials from the Atlassian doc sprintIn depth reference documentation:

Updates to existing tutorials:

The associated source for each tutorial is on Bitbucket. We have also classified all our tutorials by task and by level of experience required: See the big list of plugin tutorials.

How do we do it?

A doc sprint takes a lot of planning and preparation up front, and review and tidying up afterwards. But it’s worth it. A doc sprint is a good way of getting some high quality documentation written, and the effort spent in the preparation ensures that the developers get off to a flying start on the day of the sprint.

New Jira 5.0 tutorials from the Atlassian doc sprintFor that to happen, we needed:

  • A wish list of the plugins and tutorials that we would like to develop.
  • A template and guidelines for the documentation part of the tutorial.
  • Technical guidelines for the coding part.
  • A wiki to put stuff on.
  • A development environment, including the Atlassian Plugin SDK, a repository (Bitbucket) and a build server (BEAC).
  • The venue, network hub and cables, extra power points.
  • Online chat room, video conferencing, webinars and an email group.
  • Chocolate.
  • People. It’s all about the people!

We started planning a month before the date, by defining the scope of the sprint (Jira 5.0 Java APIs) and a wish list of tutorials to develop. We talked to product managers, development team leads and customers, to refine and prioritise the wish list. Then we invited the sprinters and asked them to put their names down for a tutorial, even before the sprint started. This gave them an idea of what they would be doing and helped us to know that all the important tutorials are covered.

The sprinters are the stars: Matt Quail, Ben Woskow, Jonathan Doklovic, James Winters, Cheryl Jerozal, Ian Grunert, Ben Speakmon, Rich Manalang, Michael Tokar, Nick Menere, Mark Lassau, Giles Gaskell, Jonathan Nolen, Wojciech Seliga.

New Jira 5.0 tutorials from the Atlassian doc sprint

What was it like?

Fun, busy, rewarding. We exposed our new technical writer to a doc sprint on her first day! That’s a great welcome to a technical writing team.

A doc sprint is like Atlassian ShipIt Daysquared. We needed to write a plugin and a document. Two days is not a long time. Some people were intending to develop a multipart tutorial, but found that there was only time to do the first part. Others found that they were diving too deep into the code, and decided to rethink and simplify their tutorials on the morning of the second day. Most people were happy to finish and polish their work in the few days following the concentrated 48 hours of the sprint.


I enjoyed doc sprint so much I am doing it again today.

The developers found the experience educational too. In particular, a few people remarked that they had gained a better understanding of what it was like to develop a plugin, as opposed to writing the APIs. It’s “great to put yourself into the plugin developers’ shoes“.

New Jira 5.0 tutorials from the Atlassian doc sprint