Blog Archives

Introduction to agile methodologies

This week I attended a short introductory session to agile methodologies. An Atlassian colleague, Stuart Bargon, gave us a great overview of Scrum, Kanban and Extreme Programming (XP). We also had a brief discussion about how we can improve the integration of technical writing into the agile development process. These are my notes from the session.

To kick off the session, Stuart asked us what we already know and understand about agile methodology. There was an interesting range of answers:

  • One of the technical writers has documented GreenHopper for a year and a half, and therefore understands agile as a use case for that tool.
  • Another person went into details of the scrum and issue tracking procedures he’s experienced in the development teams.
  • Someone else had read the Agile Manifesto and understood the aims, but had never put it into practice in a team environment.

The Agile Manifesto

Stuart discussed each of the principles of the Agile Manifesto, illustrating some of them with examples from his own experience.

  • Inevitably, we dwelled a while on the point about “Working software over comprehensive documentation”. We didn’t come to any specific conclusions though, other than that everything is relative.
  • I said that my favourite principle, and one I think Atlassian does really well, is: “Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.”
  • Stuart pointed out that this one is particularly relevant to technical writers, in that it emphasises the diversity of skills amongst team members: “Business people and developers must work together daily throughout the project.”
  • Another one relevant to us, in our role as technical communicators: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”
  • Concerning the point about self-organising teams: “At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.” Stuart pointed out that this is not a licence for a free-for-all. From a management perspective, the idea is to create an environment that gets the team to organise in the way you want it to. People are more motivated if they decide they want to do something themselves.

I found this point interesting: Many of the ideas in agile methodology come from the way Toyota works. In particular, Toyota’s teams regularly stop and examine their work to see how they can improve the quality. See the book “The Toyota Way“.

Agile disciplines

These are the methodologies we touched on:

  • Extreme Programming (XP) – a set of processes
  • Scrum – a lightweight process
  • Kanban – an even more lightweight process

Generally, agile practitioners pick and mix these days. They take bits out of the various disciplines to suit their needs.

Extreme Programming (XP)

We touched on the principles of Extreme Programming. It’s important to note that not many people follow all the principles devotedly. Instead, people take the bits they need. See this diagram of the Extreme Programming project.


Stuart ran through the basics of the Scrum process:

  • Write feature requests as “stories”. You should include the specific persona and the reason that persona wants to perform the task specified.
  • The “product backlog” is the list of stories in order of priority. Stories at the top of the list should be small. The stories at the bottom of the backlog tend to be just ideas and perhaps still rather big chunks. They must be broken down into smaller stories as they approach the top of the list. Some people use the concept of an “epic” to group related stories and keep them together as they approach the top of the list.
  • The “sprint backlog” is the list of stories to be tackled in a particular sprint.
  • The “sprint” is a period (often two weeks) during which the development happens. There’s a planning meeting at the beginning of the sprint and a retrospective at the end. The idea is that each sprint delivers a potentially shippable product.
  • Scrum defines 3 roles: The product owner creates and prioritises the backlog, defines the stories, decides what goes into the next sprint. The scrum master works with the team day to day and is focused on the current sprint, fixing anything that’s stopping the team from working. The team does the development work.
  • When estimating the stories, you try to use the idea of “story points” rather than time. The story points are expressed as a number, based on the relative complexity of the work required.
  • You work out your “velocity” based on the number of points that you have managed to complete during the sprint. For example, if you had an estimate of 10 points for the stories in a sprint, and completed 8 of them during the sprint, then your velocity is 8. You can work out an average over a number of sprints, and use this to compile estimates for your product backlog.

Stuart gave us a number of good sites for information about Scrum:


Stuart remarked that the processes of Kanban are even simpler than Scrum.

The first step is to map the workflow of your development team. Stuart drew a number of columns on the board:

  • Scheduled
  • In development
  • Ready for QA
  • In QA
  • Ready for deployment
  • Deployed (Done)

You then set limits on the columns, determining the number of cards (tasks or issues) that can exist in a column at the same time. For example, the above set of columns might have these limits: 4, 2, 1, 3, 3.

A good guide for setting the limits on the number of cards is the team size. For example, if you have 10 team members, the total number of limits across all the columns should add up to 10.

The idea is that anyone can write a story and put it on the board. You can reorder the items in the “Scheduled” column.

A developer takes the top card from the schedule and puts it into the next column (“In development”). When development is finished, the card moves into the next column (“Ready for QA”).

But you can’t put a card into the next column if the column is already full.

If a card cannot move into the next column, that means that the person who wants to move it must first tackle one of the cards in the column that is blocking the flow. In this way, the work flows through to the last column. Nothing has any value until it’s in the last column. There’s no value in the whole process unless it’s producing a number of cards in the “Done” column.

One of the attendees remarked that Kanban probably requires more behavioural change than Scrum.

Cards: Agile in a Flash

Stuart took us through some of the cards in a pack called “Agile in a Flash”. I’ve found these links referring to the pack: The Agile in a Flash blog and the entry on O’Reilly Media.

The cards cover the principles of standup meetings, retrospectives, values and principles, coding standards, code ownership, test-driven development, story prioritisation, why you would want to use agile methodologies, and more.

Story prioritisation

We took a quick look at how you prioritise stories.

  • First triage the stories. Assign story points, rather than trying to prioritise the stories in order of importance/desirability first.
  • Break them down into smaller stories if necessary to fit into a sprint.

Stuart told us a funny story of a developer who had tried to break a story into smaller stories. The story was a web form that was rather long, with may fields. He broke it down into a number of stories, each containing just one or two fields. Instead, he could have produced the whole form in one sprint, but with less complex validation and business rules. The first approach makes it difficult for testers and technical writers to do their work within a sprint, because there is no story that contains the entire form.

Stuart also discussed ways of prioritising stories by putting them in a quadrant, with axes such as complexity and business value.

In a sprint, it’s best to do the high risk things first because then you can deal with any issues that come up.

Contact with customers

Contact with customers is one of the agile ideals. It’s interesting to note that, as technical writers working at Atlassian, we have quite a bit of contact with customers. We work on a wiki, where people comment on our docs. They also see our names and email addresses on the docs, and email us directly. And they can make requests of us and the development teams via our public JIRA issue tracker.

How can technical writers work within the agile framework?

We didn’t have time to discuss the specifics of how the different product teams work, and how we technical writers can better integrate our work into the processes. Just a few general comments came up.

  • Log the documentation issues in the development team’s issue tracker.
  • Get rid of the lag: the scenario where the technical writers develop the documentation after the developers have finished their sprint. We had a bit of a discussion of the obvious challenges: Things do change during and after the sprint, so the technical writers will need to keep up with the iterative process too.
  • Push back and insist that the developer teams finish stories in a sprint, because otherwise it makes it difficult for the technical writers to do their work.
  • Sit down with the scrum master, explain the challenges and discuss the solutions.
  • Highlight any problems during the retrospective.

We discussed the idea of getting the documentation included in the “definition of done” for a development issue. There are pros and cons. For example, a pro is that the development team will be more aware of the work the technical  writers are doing and of what needs doing. A possible con is an increase in the tension between the development and the technical writing teams.

Stuart mentioned that in an agile team, there’s less of the idea that a team member is a specialist. Rather, each developer can work on any story. This could also work with the technical writers when embedded in the teams. The technical writers can give more input during planning meetings, into the design of a feature and how it will affect other parts of the product. Similarly, developers can do the drafts of the documentation to ensure it is all finished within the sprint. If you use a task board, such as in GreenHopper, you can see quite clearly the stages that the various stories are in. If a number of them get stuck in the “documentation” phase, that will be clear to the entire team. Therefore people will be more likely to jump in and grab a documentation task off the sprint backlog.

Agile pairing

Introduction to agile methodologies

I took this shot a few days ago, of two dragonflies locked in passionate embrace. They don’t look very agile, do they? Actually, they zoomed around quite efficiently, even in flagrante delicto. That’s agile pairing for you.

In conclusion

It was interesting to hear a summary of agile methodologies from an expert in the field. As someone who lives and breathes agile, Stuart was able to condense the essentials into a very short session and add some great titbits of personal experience too. I’m looking forward to the next session, which will cover specifics of the processes followed by the Atlassian development teams. We will discuss how we can better integrate technical writing into those processes. Thank you Stuart for a very useful introduction to agile methodologies.

Update: A few hours after I published this post, Mary Connor wrote an awesome post over on Clever Hamster, entitled How does Agile affect documentation? If you’ve got to the end of my post and want to take the next step, Mary’s is the one for you.

A blitz test of the documentation

This week at Atlassian we held a blitz test of the documentation that we were soon to publish with an upcoming software release. It was fun and productive. We made some nice improvements in the documentation. As a bonus, we found a cute bug in the application itself when we tested the procedure against the step-by-step guide.

Our QA team first introduced blitz tests, to test the applications themselves rather than the documentation. We decided to try it out on the documentation too.

What is a blitz test?

The doughty blitz testers

In a blitz test, people from all walks of life spend an hour doing concerted and concentrated testing of specific aspects of the product. It’s a way of timeboxing the testing. It’s also a way of viewing the product as whole rather than the disparate bits that have previously been reviewed individually. Best of all, it’s a way of working together on improving the product.

To say “people from all walks of life” is a bit of an exaggeration, of course. The point is that the developers, technical writers, product managers and various other people join the QA team and that we all work together for that hour on testing the product due for imminent release.

As technical writers, our product is the documentation. For this blitz test, we targeted the documentation for the release of Atlassian Crowd 2.1.

Preparing for the blitz test

First I contacted the development team leader and product manager to check whether they liked the idea of the team taking part in a documentation blitz test. They were enthusiastic. The Crowd team are great. 🙂

The next step was to create a test plan that everyone could work off, with the following information:

  • Date and time of the blitz test.
  • Names of the testers.
  • Location. We held a kickoff meeting in the team area and then the testers worked at their own desks.
  • Aim and scope of the blitz test.
  • A list of all the new and updated documents that I wanted tested, grouped by functional area in the application.
  • The test environment. In our case, we were testing the draft documentation on our production documentation wiki.
  • Where and how people could record their test results and feedback.

At the appointed date and time, we all gathered in the area around the development team’s desks to confirm that everyone knew the areas of the application and the documents to be tested. We allocated one or more areas and documents to each person, and checked that everyone knew where to put their results and which chat room to join.

It’s on! People rushed back to their desks, the room took on an air of frenzied quiet, and the chat room and wiki exploded into action.

How did the testers provide their test results?

We offered various ways that people could record their results:

  • Edit the documentation pages directly. The documentation is on a wiki, so that was easy.
  • Add comments to the documentation pages. The pages were in draft status, so the content and the comments were visible to Atlassians only.
  • Chat about the test findings in the team’s online chat room.
  • Ping me on IM.
  • Add a child page to the test plan on the internal wiki, documenting the test findings there.
  • Add a comment to the test plan on the internal wiki.

The results

The development team were positive and enthusiastic about the experience and jumped in with a will.

  • The development team leader suggested a few small additions to the more technical documents, clarifying the impact of changes and new features.
  • A developer pointed out a page where the terminology used on the screens had changed again after I’d updated the documentation. We needed new screenshots and a change to a page name. Phew, that was a biggie.
  • Other developers pointed out a number of small clarifications.
  • Someone pointed out a change in behaviour that was actually a bug. Nothing major, just that the “Continue” button in one of the wizards no longer worked in the same way. You now need to click a tab instead of a “Continue” button when you want to move to the next stage. 🙂 I’ve updated the documentation and we’ll fix the bug in the next release. At which stage I’ll change the documentation back again.
  • Someone else found an issue that he’d fixed in the code, but had forgotten to mark as “fixed” in the issue tracker. The result was that I hadn’t updated the documentation, of course. This was a fairly big find too. Phew again.

Some feedback came directly to me via IM. What a good thing that you can copy and paste from an IM conversation!

Did anyone update the documentation itself? Yes indeedy! The product manager tweaked the release notes, and noted that he would produce some performance stats to illustrate a point.

What did the developers think of the documentation blitz test?

The Crowd team's standup toy at rest in the clasp of a monkey

After the blitz test was over, I asked the development team what they thought of the experiment. Here’s their feedback about why they thought it was beneficial:

  • Team ownership of the documentation.
  • Team building.
  • The obvious verification that what we’ve specified in the docs is correct.
  • It can be worthwhile double-checking the docs in case functionality or edge cases are missed in the docs (because we may have subtly changed the implementation without notifying the tech writers).

Was the blitz test a Good Thing?

From my point of view as technical writer, it was very valuable.

The development team and product manager had already reviewed the documentation piece by piece, as I developed it. The blitz test gave them the opportunity of viewing it as a whole.

People continued updating the documentation the day after the blitz. We released the software and published the documentation two days after the blitz test. We’re on a roll!

Technical writer’s pick of presentations from Atlassian Summit 2010

Technical writer's pick of presentations from Atlassian Summit 2010

Technical writer's pick of presentations from Atlassian Summit 2010

Last week I attended Atlassian Summit 2010 in San Francisco. Summit is a conference hosted by Atlassian (the company where I work, though I’m in the Sydney office) for our customers. Because I was “on duty”, I didn’t get to attend as many of the sessions as I would have liked. The conference was awesome, and the sessions were of a very high standard. Luckily, they’re available on video.

There are a number of videos on the Atlassian Summit 2010 site – one for every single session. I’m sure you’d love to watch them all, but that will take a bit of time. Someone told me they amount to 40 hours of viewing!

So I’ve had a look at the videos and picked out a few that I enjoyed and that are particularly relevant to technical writers:

  • Confluence at NASA: Where No Wiki Has Gone Before, by Nick Smith of Freedom Information Systems. Nick has two aims: Firstly to inspire us, by letting us know that NASA uses the same tools as we are using. In particular, Confluence wiki. And secondly to let us in on the things they’ve learned from using the NASA wiki. Nick’s talk is a case study of the Ares Preliminary Design Review that took place in 2008. They created the “Ares Reviews Wiki” using Confluence. Thousands of people used the wiki to review a set of 75 documents (large, complex documents) over a period of two weeks. The documents were the design specifications for Ares I Rocket, a replacement for the Space Shuttle. Nick tells of the success of the project and runs through the lessons they learned from the project. Very useful, and an engaging presentation style. Good work Nick!
  • Building a kick-ass Confluence page in 10 minutes, by Matt Hodges of Atlassian. This is an awesome lightning talk where Matt shows us how to use some advanced Confluence features to build a complex page in 10 minutes. I attended this session in real life, so I know it was great. A definite must-see.
  • Felt the earth move when I read your docs, by Sarah Maddox of Atlassian. Rumour has it that I attended this one too. 🙂 This was my presentation, taking up the first 22 minutes of the video. It’s all about using social media to engage your readers in the documentation. I’ve also written a summary blog post with links to the download files and video.
  • Confluence as a Support Knowledge Base, by Jeremy Largman of Atlassian. Jeremy and I shared a session. Jeremy’s presentation is in the second half of the video, starting around the 22 minute mark. He talks about using Confluence as a support knowledge base and the tools the support team have built to extend Confluence. His presentation is awesome and packed with information. Well worth a watch.
  • Labels Magic – Using Labels in Confluence to Manage Information for a Release Cycle, by Anthony Pelosi from the San Francisco User Group. One often-cited problem is how to find content and information in the wiki. Anthony gives a great demonstration of using labels and the content-by-label macro as a flexible approach to organising and finding information.
  • No Coding Necessary – Building User Macros and Dynamic Reports Inside Confluence, by Charles Hall of Astrium. This session is for more advanced and technically-oriented Confluence users. Charles Hall starts with a great introduction to user macros, what they are and what you can do with them. No coding necessary… well, except a bit of jQuery and… ! Now Charles rolls up his sleeves and gets serious. This is an excellent session for people who want to do more with their wiki.
  • Building Awesome Dashboards with Confluence, by Jim Severino of Atlassian. In the second half of this session shared with Charles, Jim Severino describes how to build awesome dashboards with Confluence. He starts off by showing some of the Confluence pages we use at Atlassian, showing graphical reports and data in a dashboard-like format. Examples are product revenue dashboard, a build and infrastructure dashboard, customer services graphs and so on. Next Jim tells us about the free plugins available that you can use to manipulate data, all created by customers and available on the Atlassian Plugin Exchange. Jim goes on to tell us how to use the plugins to create graphical data dashboards on Confluence. A very interesting and informative session, again for people who want to do extra magic on their wiki.
  • Mastering JIRA Workflow, by Christina Bang of Atlassian. This is an awesome in-depth look at JIRA workflow, by someone who really knows her stuff. JIRA is a web-based tool for project management and issue tracking, developed by Atlassian. Watch the video then download Christina’s expert guide to JIRA workflow. The PDF file is linked above the video. Essential viewing if you want to change the basic, default workflow to suit your team and your procedures. In particular this is relevant to technical writers who may need to adapt the default, software-development-based JIRA workflow to create a different set of steps and statuses, issues and tasks more suited to documentation development, review and publication.

There are some other really great sessions that I haven’t mentioned here, with lots of useful technical and procedural tips. In particular, if you’re interested in agile software development, you may find some useful sessions on the Summit site. I hope my selections give you lots of happy viewing.

Planning a doc sprint

We held our first doc sprint a few weeks ago, and it was awesome. Even the moderately stressed organiser (that’s me, folks) had a lot of fun! We wrote some very shiny tutorials. My earlier post was about the people and the results, so now I thought you might like to hear about the planning and organisation that went into the doc sprint. All the stuff we learned. In case you’re thinking of doing one yourself.

A “doc sprint” is similar to a book sprint. We called ours a doc sprint because it focused on technical documentation and on developing a set of tutorials, rather than a single book. We invited a number of developers to join the technical writing team in a three-day sprint, with the aim of producing some quality tutorials on gadget and plugin development.

Update on 12 September 2012: I’ve published a new post about running a doc sprint, with lessons learned from the last few sprints we’ve run: How to plan a doc sprint. Maybe you’d like to glance through the post below, and then move to the more recent one.

Are ya ready? I feel a mega post coming on. 😉

What did we get up to during the doc sprint?

We shut ourselves up in a room, told everyone else to keep away because this was documentation quality time, and wrote like maniacs. We also ate chocolate, composed haikus when our brains needed a break, bombarded Google Talk with inanities and held “remote standups” via webinars.

Why remote standups? Because we had 20-odd sprinters in Sydney, 2 in San Francisco and 2 somewhere else entirely. We flew 2 sprinters in to Sydney from our San Francisco office and generally mixed things up. The sprinters are all in our Doc Sprint Hall of Fame.

Two people even joined us a week late. We figured out how to do remote standups but alas, we haven’t yet managed time-travelling standups. 🙂 That said, the wiki does a fair approximation. All our content is still there. The two tardy sprinters just grabbed a template and got going.

Doc sprinting in the basement

Doc sprinting in the basement

When to start planning

Early. We started planning in early November, for a sprint scheduled for mid February. That gave us three months to get our ducks in a row. I’m guessing that we won’t need as much time to plan the next sprint, but certainly the first takes a lot of thinking and planning.

In our case, we wanted to  invite people to travel from the United States to Australia, so we needed to give them plenty of warning and we needed to get budgetary approval from management. We were also not sure how many external sprinters we’d have. By “external”, I mean people who are not Atlassian employees. (Atlassian is the company I work for.)

Involving your team and management

One of the greatest things I found is just how enthusiastic, generous and inventive people are when given an idea to play with. My advice is definitely to get your team involved as soon as you can. Start a wiki page or a Google Doc, hold a kickoff meeting and throw around some chocolate. The ideas will start flooding in! I wrote about the people in my previous post, but it’s worth mentioning here again:

The people are the best part of a doc sprint.

Setting up a wishlist of documents

I wanted to give people something to get to grips with, so that they knew what they would be doing if they signed up for the sprint. I figured it would give them more impetus to join the sprint and it would get the first day of the sprint itself off to a running start. I also wanted people to feel that they could add their own ideas about what documents we needed.

We started by defining the focus of this particular sprint: tutorials on how to develop plugins and gadgets for the Atlassian applications.

I created a wiki page on our intranet wiki, seeded it with a basic list of tutorials that I thought we needed and asked Atlassians for input. After a few weeks we had a good if somewhat unfocused list. Next I chatted to our CEOs and other leaders get their input. Finally we held a brainstorm meeting to hone the list down to a good size and to make sure each tutorial covered a single topic. (Well, more or less. That was the idea, anyway.)

Next, I put the tutorial wishlist on the public wiki and invited the whole wide world to look at and update it. In practice, the “whole wide world” is the community developers, partners and doc sprint invitees.

We also suggested to the doc sprint invitees that they put their names down next to the tutorials that they would like to develop. If they wished, they could partner with another developer on the same tutorial. Doc sprint pairing for the win!

The resulting tutorial wishlist gave everyone a focus. Come the first morning of the sprint, many people dived right in without even waiting for the kickoff meeting.

Communication plan

It works well to map out a plan of the blogs, emails and other communications that you’ll send before, during and after the sprint. When things hot up, it’s all too easy to forget to send the final reminders or even to kick off the first webinar! A communication plan also helps to make sure you don’t spam people at some times and then leave them in the dark at other times.

The communication plan can be very simple. Here’s what ours looks like:


Planning a doc sprint

Planning a doc sprint

Inviting people

Have a good think about who to ask. Do you want to involve people outside your organisation, such as community developers, community authors, or partners? Maybe you want to limit the sprint to internal developers. Decide if you want to look outside your team, and whether you’re inviting technical writers only, or developers, or all sorts.

When should you send the invitations? If you’re planning to invite people to fly in from other cities, I think two months is a good time frame. For people who are in the same office as you, or people who intend to work remotely, then one month is OK. After all, which of us knows now whether we’ll actually be free to contribute to a doc sprint in two months’ time?

I sent out invitations in the form of blog posts like this one, as well as personal email messages to known members of the developer community. When the sprint date drew close, I sent out a reminder blog post and email messages.

I also tweeted copiously about the sprint. After all, it was a big event in my working life and in my team’s life too.

Why do people take part in a doc sprint?

What motivates people to give their time and skills in a doc sprint? Before composing the basic text of the invitations, I had a good read of this study on why people are willing to contribute their time to community documentation projects: Why do people write free documentation? Ours is not exactly free documentation, but I think the same sort of motivations apply. (Basically, people are just awesome.)

People enjoy learning cool stuff from the other experts on the sprint. External developers enjoy the contact with Atlassians, and Atlassians enjoy and learn from the external developers who are using our tools. People like helping other people. They get a sense of satisfaction from fixing documentation that is out of date and from developing a new tutorial that is as near perfect as possible.

One of the external attendees mentioned that the personal email invitations were very powerful. If you already know some of the people you are inviting, or know something about their previous and ongoing contributions to or questions about the documentation and code, then it’s really nice to put that in the email message. It makes sure that you think about the person you’re writing to. They can see that when they read the invitation.

Templates and style guide

We already had a style guide and I included mention of it in the invitations. But to be honest, I don’t know that many people paid attention. It’s probably too much information.

Templates, on the other hand, were extremely useful. They got people up and running quickly (reduced the fear factor) and they give a basic framework that is standard across all the tutorials. I created a template for each type of tutorial we were planning to write:

During the course of the doc sprint, people suggested additions and improvements to the templates. I applied the updates on the spot, and let all the sprinters know. In some cases, we needed to apply the updates to some of the tutorials after the sprint, because the template updates were too late for people to take into account. That’s cool. The main thing was to get the tutorials written and as perfect as possible during the sprint. It’s a bonus that we now have improved templates for use in another sprint and indeed in day-to-day document authoring.

Wiki or web page visible to outsiders

It’s very useful if you can publish details of your doc sprint to outsiders, and even more useful if you can allow all comers to update the information. We have a tame Confluence wiki, so we created a Doc Sprint space and opened up the permissions of that space so that all logged-in users can edit the pages. That meant that would-be attendees could simply add themselves to the list and put their names down next to the tutorials they fancied. They even added suggestions to the tutorial wishlist. This helped people to feel involved immediately, long before the sprint started.

We also published a schedule showing the activities day by day. At first the schedule and other information on the wiki was a bit bare. We fleshed it out as the sprint date drew closer. (LOL, I see that the schedule page still announces that it’s not yet final. That’s agile for you!) The schedule shows the activities day by day, split by time zone, including the webinars, meals, fun activities, show and tell, retrospectives and so on.

Online participation

For us, a good set of online communication tools was essential because we had sprinters in different countries and different time zones. Even if you’re all in one room, though, I think an online chat group and a wiki are indispensible.

Ed set up the online group, chat room and webinars for our sprint:

  • A Google Group, so that we could sent emails to all sprinters.
  • An online chat room using Tea Party, which we accessed primarily through Google Talk. Note that some people said they would prefer IRC or Jabber conference.
  • A series of webinars (online conference meetings) hosted by GoToMeeting.

The webinar sessions worked very well. We used them to kick off the sprint, to take the place of standups during the sprint, and to conduct the final presentation and retrospective for the remote sprinters. For the daily webinar, we kept to the same format as standups (meetings held standing up, a mainstay of agile development). Each sprinter said what they had done so far and what they were planning next.

Just as in a standup, this led to useful interactions. For example, Daniel (in Sydney) mentioned an error that he had encountered while developing a JIRA plugin. Matt (in San Francisco) said he was interested, and later got the details from Daniel to include in his sprint document about common error messages when writing JIRA plugins.

Hint: Schedule a practice webinar before the sprint starts, so that you can get to know the webinar software.

Write up a plan for the first webinar, which is in effect the kickoff meeting. Our webinar agenda included such things as introducing the sprint, asking people to introduce themselves, showing people the templates, explaining the format and logistics of the sprint, and so on.

We also made sure we had a development environment set up. In our case, people needed to write code as well as documents, so we needed a source control repository and a continuous integration server that will run their tests. The documents themselves were fairly easy: we put them into the doc sprint wiki space. We had already set the permissions in this space to allow any logged-in user to add and edit pages.

Here’s an extract from our online chat group. Check out the mishmash of technical and fun stuff comments. Could make a good rap song, I reckon.


Doc sprint chat

Doc sprint chat

Catering, venue and other practicalities

There are a lot of practicalities to consider: Mundane things like tables, chairs, network hubs and signs telling people where to go.

It’s useful to tell people what they need to bring. In particular, they’ll probably need to bring their own laptop computers.

Find out what your budget is. Will the company or the sprint organisers pay for any meals? Then let the sprinters know, so that they can decide what to do about their meals. If you’re taking people out for dinner on the last day, or any other occasion, don’t forget to book a table in a restaurant.

We had a long list of tasks on the planning wiki page, with a person’s name next to each task. I added even simple tasks like booking the restaurant into the plan, because I knew I was likely to be in a tizzy and forget to book. Think of the satisfaction you’ll have as you tick off each task.

Theme and fun

Planning a doc sprint

The one and only theme

A theme is great for making a doc sprint sound like fun, giving it and the sprinters a sense of unity, and just plain prettying up the wiki pages!

We agonised for a number of days about choosing our theme. What could it be? Something to do with the Hitchhiker’s Guide to the Galaxy? A sports car or running theme, to fit with the word “sprint”? The one and only theme occurred to me in that most inspirational of places — the E66 bus on my way home one evening:

Chocolate, of course!

Once we had a theme, Andrew could perfect his ideas for fun stuff.

Another tip: Don’t forget to organise some cameras! I pestered the remote participants to take photos of themselves too, so that we could include them in the Hall of Fame.

The most important task

Most important of all was, of course, to buy the chocolate. For this task you need exquisite timing combined with impeccable taste. We had asked our sprinters to pick a chocolate-related middle name. Unbeknownst to the sprinters (and unbeknownst to us too, until Ed thought up the idea much later), we would give each participant their “name chocolate” at the sprint. Here are a few of the names people chose:

  • Rich “90% Cocoa” Wallace – Some people are serious about their chocolate.
  • Jonathan “Choco Taco” Doklovic – Jonathan was a remote participant. I’d never heard of Choco Tacos, but they look like a suitably decadent treat for a technical writer. Alas, I had to persuade Jonathan, reluctantly, that it wasn’t practical to post a Choco Taco to him and we sent an Amano Ocumare chocolate bar instead. I hope it was at least as good!
  • Andreas “Ferrero Rocher” Knecht – I love the way this name rolls off the tongue.
  • Ben “Smarties” Speakmon – Ben, a San Franciscan, had heard that Smarties in Australia are quite different from Smarties in the US. He flew in to Sydney for the doc sprint, toting a huge bag of American Smarties. We gave him a box of Ozzie Smarties. A large part of the first webinar was taken up in exclaiming over the differences.
  • Erik “Chocolate Salty Balls” van Zijst – Don’t even go there.

Here’s part of the haul after I went shopping:

Planning a doc sprint

Planning a doc sprint

Presentations (show and tell)

We scheduled the doc sprint presentations for 3pm on the last day. Everyone knew that at 2pm, they needed to down tools and concentrate on getting their presentations in order. We decided to keep it simple: each person had 3 minutes to walk through their tutorial, explaining its purpose and its cool flashy parts.

Having a deadline like this was a great motivator. It gave everyone something to work towards, and finished the sprint with a bang.

Presentations in the boardroom

Presentations in the boardroom


We also held a couple of retrospective sessions, to get feedback and suggestions from attendees, to hear what they thought went well and so that we can do things better next time. Giles organised a very efficient and thorough process, using the wiki to gather comments from all attendees scattered across the globe. In Sydney we met with all sprinters immediately after the presentations, to go through the comments in detail, adding more suggestions as we went along. Then we held a webinar session to do the same with the San Francisco sprinters and anyone else who could attend.

Giles then summarised the results and published them on the wiki.


Dude, these don't look like no Smarties I've ever seen

Dude, these don’t look like no Smarties I’ve ever seen

Flexibility in the planning

All the planning paid off very well. But it’s also worth knowing that people changed their plans a fair bit during the first day. It was agile at its best. We started with the tutorial wishlist, and most people had a tutorial already assigned to them. But then they found problems with the SDK (plugin software development kit) or things that would take too long or be otherwise impractical for either the tutorial or the sprint. Some people discovered that it would be more efficient if they paired with another developer on a different tutorial. Some people decided that the reference documentation needed more tender loving care than a new tutorial.

The thing is, we had the experts in the room and it was just great to have them looking at the documentation, deciding what needed doing, and then doing it. This is what the sprint was all about. We just gave them the opportunity to do it.

How much sprinting can you do if you’re the organiser too?

This is a really useful thing I learned! If you, as organiser, are planning to develop any new documents or tutorials yourself during the sprint, make sure you assign yourself something simple and short. You will be very busy, even during the sprint. People will come to you with all sorts of “interesting” questions – ranging from bugs in the SDK (software development kit) to where to go for lunch and where’s the fan that should have arrived yesterday! You need to feel free to devote time to things like updating templates, telling people what’s happening, taking photos and writing notes for the post-sprint blogs.

I chose to develop a really simple tutorial because I guessed I wouldn’t have time for much else during the sprint. Phew, I was right!


I think it’s important to acknowledge the great work people have done. They have contributed a lot of time and expertise on something that isn’t their day job. Some of the rewards are inherent in the doc sprint itself, such as learning cool stuff from the other experts, having contact with external and internal developers, helping others, and developing a satisfyingly perfect tutorial. Even so, it’s enjoyable and nice to recognise people’s contributions.

We created a Doc Sprint Hall of Fame, showing all participants with the tutorials they wrote and a photograph taken during the sprint. I’ve also written a few blogs, on the Atlassian blog as well as here on ffeathers, mentioning the great work people have done.

There’s not much more we can do, really, apart from promise the sprinters that they’ll be first on the list for our next doc sprint. 🙂

Inevitably there will be a bit of tidying up in the tutorials themselves. We put ours through a technical review, and we also intend to do a technical writing review as soon as time allows. We’ve also moved them from the “Doc Sprint” space on the wiki into the Developer Network space along with the other tutorials.

Other resources

Here’s a collection of good resources and ideas:

In a nutshell

Are you thinking of doing a doc sprint? Go for it. It’s great! Let me know how it goes, or if you  have any questions that I may be able to help with. 🙂

We held a doc sprint and it was awesome

We’ve just held a “doc sprint”. We put twenty developers in a room for three days with some computers. And some chocolate. We didn’t know whether to expect some shiny new tutorials or the complete works of Shakespeare. Or perhaps a new motif for a chocolate wrapper.

So, what did happen? We had a lot of fun and produced 19 awesome tutorials on how to develop gadgets and plugins. A few developers opted to spend the first day of the sprint looking over the existing reference documents and doing a mass update, before starting the tutorials. Some even decided that this was the most valuable exercise for the entire sprint. One person was heard to exclaim, “The biggest sign of victory is how many pages I managed to delete.”

The people

I think that the people are the best part of an event like this. Give people a focus, an opportunity and something to be excited about, and they climb in and do awesome stuff.

Handing out chocolates at the doc sprint

Handing out chocolates at the doc sprint

The sprint had a momentum of its own, especially from the second day when everyone was feeling comfortable about what they were doing. I did wonder if some of the sprinters might get bored or less than enthusiastic about spending so much time on documentation. After all, most of them were developers. But quite the opposite happened. The sprinters became absorbed in developing the best possible tutorials. A number of them said we should hold doc sprints regularly.

At the beginning of the final-day presentations, I overheard this affectionately ironic exchange:

“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!”

Waiting to start the doc sprint presentations

Waiting to start the doc sprint presentations

Hall of Fame

Most of the sprinters were Atlassians, and most were based in Sydney. (Atlassian is the company I work for.) We had two sprinters in the San Francisco office, and a few “remote” sprinters who joined us online.

One of the awesome aspects was that a few sprinters were community and partner developers, who develop plugins and extensions for Atlassian products but are not Atlassian employees. I was totally delighted when these guys said how keen they were to join us and made the time to do so.

The Hall of Fame has photos of the doc sprinters and links to the tutorials each person created. There are also some photos on Flickr.

A hint

If there were just one tip I could give, after organising my first doc sprint, it would be this: Get other people involved early. It’s awesome to see how many ideas bubble up when people get together to plan something new. I’m part of a great team at work, and the doc sprint was very much a team effort. As soon as the idea came up, everyone started chipping in with ideas.

Andrew was the first, with lots of ideas about fun things to do online and in person. I quickly dubbed him fun stuff coordinator. During the sprint, our online chat room resonated with reminders from “FunStuffAndrew” about the chocolate haiku contest, chocolate blind tasting and the chocolate crossword, to name but a few. We’ve invented a whole new vocabulary! Ed tirelessly promoted our cause with the team leaders, set up the Google group and chat room and conducted the daily webinar sessions that glued the event together. Giles’s organisation of the retrospective was just awesome. It was a complicated situation for a retrospective, with sprinters working in different time zones across the world, some of them Atlassian staff members and some not. The resulting feedback was positive and valuable.

Setting up on the first day of the doc sprint

Setting up on the first day of the doc sprint

I’m planning to write another blog post soon, about what went into organising the doc sprint. For now, though, I’m so happy to say it was awesome and thank you to all the sprinters!

And the new motif for a chocolate wrapper? How about, “A chocolate by any other name. …Is this a chocolate I see before me? …Get thee to a chocolatier, go.” 😉

%d bloggers like this: