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.
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.
- Adding Content to the Jira View Issue Page
- Application Links in Jira
- Creating a Custom Field in Jira
- Displaying Content in a Dialog in Jira
- Jira Issue CRUD and Search
- Writing a Custom Message (Mail) Handler for Jira
- Creating Workflow Extensions (under review)
Two new tutorials that are useful for all plugin developers, not just Jira:
- Adding Licensing Support to your Marketplace-Ready Plugin
- Viewing OSGi Bundles and plugin deployment errors via the UPM
Updates to existing tutorials:
- Writing Jira event listeners with the atlassian-event library
- Adding a JQL Function to Jira
- Writing Gadgets for Jira
- Internationalising Your Plugin (under review)
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.
- 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.
- 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.
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“.