We have just finished our first Atlassian Doc Sprint. We put 20 developers in a room with computers for 3 days. We didn’t know whether to expect the complete works of Shakespeare or some shiny new tutorials. Here’s what happened.
The problem we tackled
We have some gaps in our plugin development documentation. OK, maybe they’re crevasses! Maybe we’ve even lost a developer or two down there. So we did some fracture mechanics analysis, identified the areas that needed most work and organised our first Doc Sprint.
The Doc Sprint
The main event happened in the Sydney office. Two people joined us in San Francisco and there were a couple of remote sprinters. It was awesome having our community developers taking part too. We had an online chat group constantly running. With the difference in time zones, there was never a quiet moment. We also held daily webinar sessions, the long-distance equivalent of standups.
We got through a huge amount of work. The main focus was on tutorials for plugin and gadget developers. Most sprinters developed a plugin or gadget to illustrate a common piece of functionality. They checked the resulting code into a public repository and wrote a wiki page giving step by step instructions on developing the plugin or gadget.
During the sprint, we created the tutorials in the Doc Sprint space. In the days after the sprint, we reviewed the tutorials and moved most of them into the Developer Network space. Some of the tutorials were not yet complete, so they’re not yet published. These are the completed tutorials:
- Plugin Gadget Tutorial – Using the Fisheye REST API to Write a Gadget to Monitor Recent Changes
- Plugin Gadget Tutorial- Writing a Gadget that Displays the Days Left in a Version
- Plugin Tutorial – Adding a Custom Action to Confluence
- Plugin Tutorial – Adding your own Menu Items to Jira
- Plugin Tutorial – Adding your own Menu Items to Confluence
- Plugin Tutorial – Creating a Jira Report
- Plugin Tutorial – Scheduling Events using SAL
- Plugin tutorial – Writing an Admin Configuration Screen
- Plugin Tutorial – Writing Integration Tests for your Jira Plugin
- Plugin Tutorial – Writing Unit Tests for your Plugin
- Standalone Gadget Tutorial – Writing a JQL Gadget
- Plugin Tutorial – Writing a Confluence Macro that uses JSON
- Plugin Tutorial – Defining a Pluggable Service in a Confluence Plugin
- The Webwork Sample plugin, a third-party tutorial describing how Jira uses WebWork
The following tutorials are still in draft. Keep an eye on the Developer Network space to see them when completed:
- Internationalising your Plugin
- Developing a Complex Gadget in Stages
- Creating a Jira Custom Field Type
- Creating Custom Workflow Elements for Jira
- Persisting Data in Confluence
Other sprinters decided to dive into the existing reference documentation, tidy it up and make sure it was up to date. I dare you to venture into the Developer Network, the Jira plugin documentation and the AUI documentation now. We’ve blown away the snow bridges made from last year’s snow, signposted the black ski slopes and filled the crevasses.
Can anyone guess what the theme of this Doc Sprint was?
- “I’ve had more chocolate in the last few days than in the last few years!” General agreement: “Seriously!“
- “It’s a good thing to feel the pain!” This was a common sentiment that became a mantra, referring to the pain that plugin developers feel when reading the existing documents.
- “This is the Doc Sprint presentations, right?” “Yes, mate. We’re gonna talk about documentation for the next two hours. It’s gonna be awesome!“
- “The biggest sign of victory is how many pages I managed to delete.” From a sprinter who decided to tackle the existing reference documentation rather than writing a tutorial.
Will we hold another Doc Sprint? Yes, every six months or so.
I wonder if anyone found that lost developer wandering around at the bottom of the deepest crevasse? Or perhaps one of the tutorials is a blindingly brilliant yet unutterably simple answer to the black prince’s famous soliloquy.
The doc sprinters were awesome! Take a look at the photos on Flickr. Thank you to everyone who took part – big kudos from all the Atlassian technical writers. To those who couldn’t make it: See you next time.