The Atlassian technical writers and friends have just held our fourth doc sprint, and it was the biggest and best yet. We had sprinters sprinkled round the world. We worked on site in Sydney, San Francisco and Amsterdam. Remote sprinters joined us online via Hipchat and the wiki. We wrote words, we wrote code, we solved chocolate anagrams. Confluence 4.3 just wouldn’t be the same without our tutorials!
Cool. So what’s a doc sprint again?
A doc sprint is an event where people get together to write tutorials and often code. The sprinters work together for a given period of time, usually two to three days, on a specific set of documentation. They tap into each other’s skills, get into the creative zone, have fun and write haikus. The outcome is a number of top-quality tutorials, plenty of learning, and a bunch of new acquaintances.
The August 2012 sprint
This sprint focused on developing plugin tutorials for the Confluence developer documentation. In particular, we knew that our existing tutorials had decayed over time. They needed updating, and we also wanted some shiny new tutorials for Confluence 4.3. So we built a wish list, invited some sprinters, and set up the doc sprint schedule.
For the first time ever, we held a sprint in Amsterdam. One brave soul joined us in the Atlassian Amsterdam office. Thanks Andreas! I hope many more people will make it for the next sprint. The chocolate in Amsterdam is to die for.
The people
A grand total of 35 people took part in this doc sprint. That includes 12 developers and writers from outside Atlassian, as well as 23 Atlassians. We had 18 sprinters in the Sydney office, 7 in San Francisco, 1 in Amsterdam, and 9 in remote locations: the UK, Israel, Germany, and the US.
Kudos to the two sprinters who travelled big miles to join us. Swapnil Ogale flew from Melbourne to Sydney, and Andreas Spall (aevolu) came from Northern Germany to Amsterdam. A big thank you also to the other developers and writers from outside Atlassian: Anne Aloysious, Bridget Rooney, Ellis Pratt (Cherryleaf), Carole Snitzer (Gliffy), Daniel Green (WikiStrat), Laura Kolker (AppFusions), David Simpson (AppFusions), Ellen Feaheny (AppFusions), Nils Bier (K15t Software), Johannes Egenolf (K15t Software).
Swapnil Ogale wrote this post: Experiencing the Atlassian Doc Sprint – Aug 2012.
The results – 30 new and updated tutorials
We now have 11 new and 19 updated Confluence tutorials – a great resource for plugin developers, nicely timed with the release of Confluence 4.3.
New Confluence tutorials:
- Working with the Tasks REST API in Confluence
- Sending Emails in a Plugin
- Posting notifications in Confluence
- Preformatted Table – Example of a User Macro
- Panel Preformatted with Specific Colours – Example of a User Macro
- Adding an Option to the Editor Insert Menu
- Adding Keyboard Shortcuts to Confluence
- Writing Soy Templates
- Writing Integration Tests for your Plugin (to be published after review)
- Altering Confluence page output using a Pipeline Transformer module (to be published after completion, some time in October)
- Defining a Pluggable Service in a Confluence Plugin (to be published after completion, some time in September)
Updated Confluence tutorials:
- Extending Autoconvert
- Adding Menu Items to Confluence
- Creating a Cross-Platform Admin Configuration Form
- Writing Macros for pre-4.0 versions of Confluence
- Preventing XSS issues with macros in Confluence 4.0
- Creating a new Confluence Macro
- Extending the Macro Property Panel
- Writing a Confluence Theme
- Writing Unit Tests for your Plugin
- Writing a Macro Using JSON
- Developing Technical Documentation on Confluence Wiki
- Developing a Knowledge Base on Confluence Wiki
- Searching using the V2 Search API (in progress)
- Writing a search result renderer (in progress)
- Adding a Custom Action to Confluence (to be published after review)
Winners!
Daniel Green and Vincent Choy found the golden tickets that we had squirreled away in the documentation. They will soon be the proud owners of a superb purple hat.
Swapnil Ogale won the haiku competition with his quietly chilling entry:
Dementors fly off
here have this, says Prof Lupin,
chocolate Potter
Planning a doc sprint
We are dab hands at doc sprints by now, having run four of them. A number of people have asked what goes into planning one. In particular, “how you identified/scoped the work to get through in the sprint, and how you geared that for community involvement”. Here goes.
The most important things we’ve learned are that every doc sprint is different, and that the most important part of a sprint is the people. If you keep the people in mind in all your planning, she’ll be right mate. 
These are the key things to plan:
- A tutorial wish list. This is a list of the tutorials and guides that you want to develop or update during the sprint. It’s crucial to the success of the sprint. Start by defining a subject area: the product or feature that you’re documenting, and the audience for the documents. For example, our sprint focused on the Confluence product. In fact, we narrowed the focus to version 4.3 of Confluence, which was due for release a couple of weeks after the sprint. Our audience was software developers who build add-ons for Confluence. Once you have the subject area, talk to the product managers and other stakeholders to define the gaps in the existing documentation. Start your wish list, and ask for feedback from everyone concerned, both inside and outside the organisation. As soon as possible, make the list available to everyone who may want to take part in the sprint. Ask for their contributions to the wish list too, and suggest that they sign up to develop a tutorial or update a document on the list. Keep refining the list and encouraging feedback right up until the sprint starts. Here is the wish list for our August 2012 doc sprint.
- The people. Decide who you’d like to take part in the sprint, and invite them in every way you can think of. Email specific people, blog about the sprint, tweet about it, use all channels of communication available to you. Get the people involved as soon as you can. It’s amazing how inventive and generous people are, when you give them something to get excited about.
One of the points raised in the retrospective after our doc sprint was: “Atlassian ShipIt had better advertising and more participation.” I find that comment very encouraging. Yeah, ShipIt, look out – you’ve got competition!
- Templates and guidelines. A template helps to get sprinters up and running quickly – it banishes that dreaded blank page syndrome, as well as ensuring consistency across your tutorials. Guidelines tell people other useful titbits, such as where to put their drafts, how to sign up for a username on the development platforms, and how much chocolate they can expect.
-
Video conference with our lone Amsterdam sprinter Development platforms and tools. The sprinters will need access to a document repository and perhaps a code repository. We used a Confluence wiki and Bitbucket. They may need a software development kit too. An online chat room is extremely useful. We had sprinters in various locations around the globe, and the doc sprint room on Hipchat never had a moment’s rest!
The Atlassian SDK has a command called atlas-run. No surprises there. But it also has one called atlas-ruin. Who dares try it? (And watch out for those typos next time!)
- Venue, catering, and other practicalities. The physical side of a sprint is fairly important too!
If you’re the organiser of the doc sprint, don’t expect to be able to do any “real work” during the sprint! You’ll be fully occupied with helping people get started, organising chocolates, organising access to the wiki and other repositories, chasing up network connections, and so on. This last sprint was awesome, because people heard that it was happening during the sprint and decided it would be fun to join us half way through. So I was busy allocating tasks, welcoming people, organising pairing sessions and generally making the whole thing work.
There’s more about running a doc sprint in this blog post: How to plan a doc sprint.
Thanks and photos
Thank you to everyone who took part. People are the best part of a doc sprint, and you made this one the success that it was. Check out the Doc Sprint Hall of Fame.
One last fact to treasure: The doc sprint trumps Atlassian ShipIt. By just one week after the sprint, we had already shipped 18 tutorials and 12 more were on their way. Yeah ShipIt, you should shiver in your shoes!