Workshops on effective writing – technical writers adding value

Our team at Atlassian has just started presenting a series of workshops for other Atlassians, on how to write effectively. People are very appreciative of the knowledge they gain in the workshops. In turn, we technical writers learn a lot from the participants. We see how much other people value our own skills. And we get a fresh look at writing and documentation, from another viewpoint. What’s more, the workshops are fun and invigorating. Added value all round!

I’m sharing the idea and content of the workshops in this post, because we’re finding them so valuable. It’s very rewarding as a technical writer, to see how much people value our knowledge and skill. It’s also interesting to see how much they appreciate a guiding hand in what we consider the very basics of writing a technical document.

Sometimes we forget just how much we know.

The format of the workshops

Each workshop takes the form of a one-hour session:

• Introductions.
• Lecture – see the material below. Questions are welcome at any time.
• Questions and wrapping up.
• Assignment of pages and posts for the workshop participants to work on at their leisure.

Before the session, the technical writer liaises with the manager of the team about to attend the workshop. We discuss the primary focus, and find out whether the team has any current plans to write documents or blog posts. Just recently in our organisation, a number of teams have put strategic initiatives in place to write and blog more. So our workshops come at a good time.

We also ask the participants and team leads to think of documents that need writing, so that their post-workshop assignments can be real documents.

After the session, the participants complete their assignments and choose one of the available technical writers to do a review. The review is a half-hour one-on-one chat, focusing on the document and any further questions the participant may have.

Kicking off the workshop

[The next few sections in this post contain the content of the workshops. The content is on a page on our internal wiki, which the technical writers use as a basis for the workshop. Participants can also use the page as a reference after the session.]

In this session you’ll learn how to write documents that people will find, read, and get what they need from. The aim is to provide a practical guide to help you get started quickly, and to put you in touch with the technical writers who can assist with reviewing your work.

We cover two types of document:

• A “how to” guide on the corporate intranet.
• A blog post on the corporate external blog.

Getting started on a document

How do you write a document?
One word at a time… not!

The big picture is the important thing.

• Sit back, think, and plan the document before you start.
• While writing, if the words don’t come, make a note and continue writing. Preserve the big picture. Come back later to fill in the gaps.

Talking to your audience

Who do you want to read the document? Who are the people you’re writing for, and what do they already know?

• Think about those people carefully. Make a mental picture of a person who has the characteristics of your target audience.
• Use that imagined person to make all decisions about your document.
• When in doubt about wording, speak to the imagined person out loud. Write down what you said. Write it down immediately, while it’s fresh. [I usually tell an anecdote here, about how some writers stick a picture of a person on their computer monitor, and talk to that picture.]
• If there’s more than one audience, consider writing a separate document for each audience. For example, consider separate documents for administrators and ordinary users.

The structure of a page

[The aim of this diagram is to illustrate that a page should have a number of headings, with short bits of text between them. After a quick look at the diagram, we discuss the sections in more detail below.]

Structure of a page

State the purpose and audience at the top

Tell people who the document is for, and what it will help them do. This will let them know if it’s the right document for them.

Separate the concepts (“what” and “why”) from the task (“how”)

Some people already know the concepts. They’ll skip past that bit and go straight to the “how”. Other people know how to do something – they’ve found the right spot in the user interface, or found the right form on the intranet. But they want to know why they should do it, or what it means.

Use “chunking”

Split the content into easily-digestible chunks. Keep them short.

Use plenty of headings, so people can find the chunk they need. Research shows people’s eyes jump from heading to heading as they skim a page.

Lead your reader by the hand

Give clear, numbered steps. Don’t skip any steps.

People have come here because they’re stuck. Don’t worry, they’ll go away again as soon as they’ve got the idea.

Add related topics and/or next steps

Send the readers away immediately if they’re in the wrong place. After that, don’t send them away until you’re sure they’ve got what they need. So, keep links to a minimum in the main portion of the page.

• At the top: In the section about purpose, add links to documents the reader may need instead of this one. For example, if you have separate documents for administrators and users, link from the one to the other.
• At the end: Put related topics and next steps at the end, when you’ve finished with your reader.

Examples from our product documentation

[At this point, the workshop participants have already absorbed a lot of theory. It's a good time to show them some examples of good and bad design. Use these examples as a discussion point. Ask the participants what is good or bad about each page.]

Good structure

https://confluence.atlassian.com/display/DOC/Deleting+or+Deactivating+Users

Good structure and design

Comments:

• Our current style is to put the related topics at the top on the right, instead of at the bottom. We’re discussing a change, because the design doesn’t work too well on mobile devices.
• Instead of a warning macro, we’ve used a panel (uncoloured) with an exclamation icon. There’s some discussion about coloured panels, and whether people skip over them when reading a page. See the references to “banner blindness” in the resources section below.
• [This is a good place to break for a quick chat about banner blindness. Find out what the workshop participants think about it, and how they themselves read a document.]

Not-so-good structure

[This is a page that has grown organically, with contributions from many people over a long period of time. It's had a revamp in the latest version of our documentation. The link points to an earlier version.]

https://confluence.atlassian.com/display/CONF50/Database+Setup+for+Oracle

Unplanned structure and design

Comments:

• No clear step-by-step flow.
• No indication of what each section is for, and whether you need to do them all.
• Other comments? [This is a good place for discussion amongst the workshop participants.]

Language and style

[This section contains a few key tips on language and style - the bread and butter of technical writers, but not necessarily well known by other people.]

Keep it short and simple

Use simple words and short sentences.

Use active voice rather than passive

[Explain the difference between active and passive. Hold a bit of a discussion here. This is a difficult concept for many people.]

Examples:

• Passive: The chocolate was eaten by the technical writer.
• Active: The technical writer ate the chocolate.

Why use active voice? It’s shorter. And passive voice can be confusing, because sometimes it doesn’t say who must do what. Imperative (command) is even better, when appropriate.

Bad:

“Your browser must be configured to xxx.”
Reader thinks: OK, so I’ll assume someone has already done that for me when setting up my machine.

Good:

“Configure your browser to xxx.”
Reader thinks: OK, I’ll do that now.

Clarify technical terms and abbreviations

Explain important concepts at the top of the page.

Spell out each abbreviation the first time you use it on a page. For example:

If you’re using IE (Internet Explorer), ….

…with regard to Workplace, Health and Safety (WHS).

Titles

The title is your most important tool for helping people find your document. This is especially true on a Confluence wiki, where people use the quick search a lot. The quick search is based entirely on the page title.

• Put the key information at the beginning of the title.
• Make the title describe the purpose of the document.

How to go about writing a page

[After quite a bit of conceptual and theoretical information, the workshop participants welcome a practical guide at this point.]

Step by step:

1. Decide on your audience.
2. Write the purpose.
   First write it for yourself, then refine it for the audience. This helps to form the content of the page.
3. Write the title.
4. Outline the document by creating the headings.
5. Fill in the details.
   Keep each section short.
6. If unsure, or struggling to find the right words, make a “TO DO” note and continue. Come back later.
   Hint: I use “xxxxxxxxxxxxxx” instead of “TO DO”. It’s quick to type, strangely satisfying, easy to search for, and stands out when I’m reviewing the page. [This bit often leads to some animated discussion amongst workshop participants. Some of them already do something similar. Others love the idea, and smile with delight.]
7. Review the content yourself:
   • Have you included everything you intended to include?
   • Can you cut anything out?
   • Should you split the document?
   • Is your language and tone right for the audience?
8. Ask someone else to review the page.
   As any writer will tell you, it’s impossible to review your own work. Your brain knows what you wanted to say, and that’s what your brain will see even if that’s not what’s written.
9. If possible, do some user testing.
   Grab a colleague from a different department. Get a different perspective!
10. Watch the page, and update it based on comments.

More about structure, at space level (specifically for Confluence wiki)

[It's time for more theory.]

We’ve already talked about the structure of page. The structure of your space also important. People often need to browse to see what’s available. Perhaps they don’t know what to search for, but they do know the general area they’re in.

Scenario: Jack searches for “proxy” and finds a page. But it’s not the one he wants. So he looks at the nearby pages.

How:

• Group related topics under a common parent.
• Use the Documentation theme to show the space structure.

Making sure people find your page

Already discussed:

• Structure of a wiki space
• Page titles
• Links to related topics

In addition to the above, let’s look at SEO (search engine optimisation) both internal (on the intranet, for the Confluence search engine) and external (on the corporate blog, for Google etc).

These are the key points for making sure people find your page or post:

• Make the title meaningful, with important words near the beginning.
• Make sure the URL contains real words.
  If you are blogging on Confluence, don’t use special characters like “?” in a page title, because the resulting URL will not contain words.
• Decide the key words for your post. These are the key concepts, and the ones the people are likely to look for when searching.
• Put your key words at the top of the post, in the introductory paragraph.
  This ties in well with our structure, where the first section contains a introduction and a summary of the story.
• Put your key words in the headings in your post.

Tools

• Templates and blueprints – make some of your own.
• Use the spell checker in the browser.
• Gliffy is great for simple diagrams.

Other hints

• Writing is a creative process, and it keeps happening even when you think you’ve stopped!
  You’ll find yourself thinking of stuff to add to your document at odd times. While walking in the bush. Or in the middle of the night. Make a note. Email yourself. Put it on Remember The Milk. Whatever works. Such ideas are gems. Don’t lose them.
• Optimise your page for people using mobile.
  No section and column macros (on Confluence wiki).
  Short sections with lots of headings.
• Limit the number of note- and warning-boxes to a maximum of two per page. Using more than this can indicate an organisational problem in the text.

Writing blog posts

[This is just a summary. We have another workshop that focuses on blog posts.]

Your blog post is likely to be technical, so the process of writing it has much in common with writing a technical document.

Here are some quick pointers:

• Maintain a character in your blog, so that people can start seeing it as a friend. Blogging is a social activity. Be yourself! Otherwise it’s difficult to maintain a consistent persona and people will soon pick it up if you don’t sound real.
• If you’re writing on the corporate blog, ask for guidelines about the tone and style to use.
• Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read.
• Make sure the title reflects the main story. This will attract readers and give you a good position in search results such as Google or Bing.
• Add structure to the content. Yes, even in a blog post. Put headings in the post itself. Split the information into easily-readable chunks.
• Give plenty of factual information, preferably hard-won. That’s what people value. Code samples and screenshots are great.
• Link to other people’s blogs. If your idea is an expansion of something someone else has written, include a mention of where you got the idea. If you’ve seen someone’s post about a related topic, link to it. The other bloggers appreciate this and will start linking back to you in return.
• Be nice, positive and sincere. If you disagree with something, say so but be constructive. Some bloggers are successful by being horrid, but to make that work you have to be really good and have a curl on your forehead. I don’t like nastiness, manipulation or one-upmanship, so I wouldn’t recommend it.

Resources

• Kurt Vonnegut:

  Here’s my all-time favourite: Kurt Vonnegut’s How to Write With Style.

  The best thing about Kurt’s guide is that it illustrates his principles so perfectly. This excerpt is from the section called “Sound like yourself”:

  …lucky indeed is the writer who has grown up in Ireland, for the English spoken there is so amusing and musical. I myself grew up in Indianapolis, where common speech sounds like a band saw cutting galvanized tin, and employs a vocabulary as unornamental as a monkey wrench.

  This bit is pretty cool too:

  Pity the readers

• Avoiding framed and decorated text boxes:
  • Banner blindness
  • Fancy formatting ignored – looks like an ad
• [Link to your corporate style guide here.]

That’s the end

In designing the content of the workshop, my aim was to give the participants as much practical guidance as possible in a short space of time. I picked the top things we technical writers know, about how to make a document work.

To add variety to the one-hour session, I chose a mix of theory and discussion sections. The sessions to date have been lively and interactive. We ask participants to complete a feedback form a week or so after each session.

The actual writing happens after the session, in the participants’ own time. They can then request a one-on-one review with a technical writer, before publishing their document either internally or for the whole wide world. Participants have expressed their thanks and said the content is useful, and have indicated a wish to attend a follow-up session.

What do you think of this type of workshop, and its potential as a way technical writers can add even more value to our organisations that we already do? I’d love to hear if you have run something similar within your own organisation too.

Change management helping customers train their staff

For our recent major product release, we published a change management guide as a quick tool for customers to see what’s changed in the product. The document is called Planning for Confluence 5. This post describes how we went about designing the change management guide, and whether it’s working. I hope this information may be useful to other technical writers and change managers.

This week our development team released a major version of the product, Confluence 5.0, with many changes that will affect the way people work. We wanted to make sure administrators know they will probably need to warn their colleagues before upgrading the wiki. We also wanted to give a good overview of the changes that will affect people’s day-to-day activities.

Defining the audience

The release notes do a good job of describing what’s new in the release. That information is primarily useful to people who are looking to purchase the product for the first time, or renew their existing licences. The upgrade notes tell administrators what they need to know before, during and after the upgrade. For this release, we needed a way of telling everybody else what was coming. Enter the change management guide.

Many organisations, especially the larger ones, develop their own procedures and training material for their staff, incorporating guidelines on using our product. The change management guide is also intended to help the people who produce those guides, as it’s a good indication of the areas of major change.

Are people finding and reading the document?

I’ve put a link on the documentation home page as well as in the upgrade notes. I’ve moved the document to the top of the left-hand navigation panel, so that it hits that sweet spot where people look first and most often. I’ve tweeted about the document, and mentioned it on Google+.

Are people finding it, and are they sticking around long enough to read it?

This report from Google Analytics shows the traffic on the page.

Google Analytics report for the page

Key dates:

• The Google Analytics report covers the period from 10th to 28th February.
• The software release date was 26th February.
• I published the document on 18th February, so that early adopters could see it. (Views before 18th February were therefore all by Atlassian employees.)
• The spike shows the highest number of hits on the date of release (26th to 27th February, in different time zones). The highest number of hits per day is on 27th February, at 486 views.

Interpreting the figures:

• People have looked at the page 2,196 times over the 17-day period.
• The number of unique visits to the page is 1,760 over the same period. So yes, people are finding the page.
• People are spending more than 3 minutes on the page, on average. That would seem to mean they’re reading it, rather than bouncing straight out.
• There’s a 57% bounce rate. In other words, people are reading this page and then leaving, without visiting other parts of the documentation site. That’s a fairly high bounce rate. For this page, I think that’s good thing. The target audience is people who already know what the product does. They don’t need to read the rest of the documentation. They just need to know what’s going to change.

Comparing this page to the Confluence documentation home page:

The home page is the most popular page in the Confluence documentation (apart from an anomaly: a page that tells people how to configure their Java home variable in Windows, which is not specific to our product).

Over the same period of time, the report for the documentation home page shows:

• 12,140 page views
• 9,431 unique page views
• 1.12 minutes average time spent on the page
• 27.8% bounce rate

My interpretation: The new change management page has a surprisingly large number of views in relation to the most popular page. (The number of views of the new page is about 18% that of the home page.) People are spending more time on the change management page than on the home page. People use the home page as a place to click through to other parts of the documentation (hence the lower bounce rate) but they leave the documentation site satisfied, immediately after reading the change management page. Yesssss!

Hehe of course, you could probably interpret the figures differently.

Designing the content of the change management guide

We chose to design the content around the concepts of before and after, which we termed “previously” and “now”. This is the primary difference between this document and the release notes. The focus of this document is on what’s changed, not on what’s new. In fact, I’d go as far as to say that if there is a new feature in the release that won’t disturb the way people work, it doesn’t need to be part of this guide.

This screenshot (it feels weird taking a screenshot of a document!) shows a couple of the “previously” and “now” images we’ve used to illustrate the changes in functionality.

For the full effect, take a look at the document itself. You can click the images to zoom in: Planning for Confluence 5.

Easy to scan

We want people to find the information they need quickly. The page includes a number of pictures as well as words. Most of the pictures are annotated screenshots. The text is important too:  People will search the page (Ctrl+F) to find specific topics.

The page has consistency of terminology and structure. There’s a short introduction, telling people the purpose of the document. There are links to related information, in case someone has wandered in off the Internet and landed on the wrong page (“every page is page one”). The table of contents on the right tells people at a glance what’s on the page.

Plenty of headings mean people can scroll down and absorb the content easily. The structural design of putting the “Previously” sections on the left, and the “now” on the right, makes it easy to grok what’s happening.

Aesthetics

The page looks good. We want readers to have a pleasurable experience of the document, leading into a pleasurable experience of the product.

Feedback

Unsurprisingly, given the way life goes on a wiki, the page has turned out to be a handy place for people to comment on the release, and for the product managers to respond. Docs alive!

The Confluence, Tech Comm, Chocolate wiki has moved to a shiny new site

The Confluence, Tech Comm, Chocolate wiki is a companion to my book about technical communication, technical writers, wikis and chocolate. This week we moved the site to a shiny new Confluence OnDemand server. Please take a look, sign up if you like, and also please consider changing any external links you may have pointing to content on the site.

The new address of the Confluence, Tech Comm, Chocolate wiki is: https://wikitechcomm.atlassian.net/

The old address was: https://wikitechcomm.onconfluence.com/

What does the move to Confluence OnDemand mean?

Confluence OnDemand is Atlassian’s new hosted platform. Our site will now automatically get the latest and up-to-datest version of Confluence. It’s currently running an early version of Confluence 5.0! So we’ll be able to play with the latest Confluence features before anyone else. If you’re interested, keep a watch on the frequently-updated Atlassian OnDemand release summary.

My seat-of-the-pants feeling is that the new site is significantly faster than the old one.

The hosted platform restricts certain functionality, primarily add-ons and customisations of the wiki. I won’t be able to install add-ons or plugins that are not pre-approved by Atlassian. This won’t have a big effect on people using the site. We no longer have the awesome add-ons from K15t Software for creation of ePub and DocBook exports. The Copy Space plugin isn’t there either. Gliffy, for drawing diagrams, is available in Confluence OnDemand, along with the add-ons listed here: Atlassian OnDemand Plugin Policy.

Existing content, redirects, and external links pointing to the site

This bit is for the 77 people already using the wiki. All your pages, blog posts, comments and other pieces of information are safely on the new site. Please let me know if you spot anything amiss.

Atlassian has put redirects in place. If you try to go to the old address, you should automatically end up on the new site. The old site will be decommissioned in a few weeks’ time. There’s no scheduled date for the shutting down of the redirect service, but it’s probably a good idea to update any external links you may have, to point to the new site.

The book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about developing documentation on a wiki. It’s also about technical communicators. And chocolate.

• Online purchase:  Amazon.com and Barnes & Noble
• Purchase also at the publisher: XML Press (The ebook version is currently on holiday sale.)

Do come and join the fun at the book’s wiki site: Confluence, Tech Comm, Chocolate wiki.

Tech comm, social media, a tweetup and a party at Tekom tcworld and AUG Wiesbaden

Tekom tcworld 2012 starts in just a couple of weeks! I’m so looking forward to this conference. The sessions look amazing. Above all, it will be great to say hallo to friends from other conferences, and to meet more technical communicators. Are you coming too? Hope to bump into you. The conference is closely followed by a meeting of the Atlassian User Group Wiesbaden. I’ve been invited to present a session there too. Very exciting.

I’ll be speaking about using social media to engage readers in your documentation.

Here’s a bit of fun: I’m learning German! I don’t think I’ll be able to say much in German, but at least I won’t look like a complete banana when people speak all round me. Well, that’s the plan anyway. I’m following a Michel Thomas course. Be kind to me.

Engaging your readers: how and why with social media

Black cockatoos in Curl Curl, Australia

Should we, as technical communicators, make use of social media to help customers use our companies’ products? How about harnessing social media to spread the word about our documentation? Even more daring: should we incorporate social media into our pages?

Have you seen this blog post on Forbes.com: The Death Of SEO: The Rise of Social, PR, And Real Content? I’d love to know your thoughts on how the topic of that post affects technical communication.

Those are the questions that I’ll address in my Tekom tcworld session. I’ll also show some real examples of social media in and around documentation, based on the experiments and projects of my technical writing team at Atlassian. Then we’ll look at the “how to”. My aim is to give attendees a set of ideas and tools for use in their own technical communication projects.

Party on Tuesday evening

W00t, there’s a Tekom tcworld welcome session on the Tuesday of the conference, sponsored by Atlassian and K15t Software.  Free beer, and a little bird tells me there’ll be some T-shirts too.

Date: Tuesday 23 October
Time: 18:00–20:00
Place: Associations World, Foyer 1st floor

It’s going to be great! Thanks to Sven Peters and the K15t Software team for organising it.

Tweetup #tcworld12

Do you know people via Twitter, and want to say hallo in real life? Or do you want to know more about Twitter and #techcomm? We’re having a tweetup at the welcome party!

Date: Tuesday 23 October
Time: 18:00–20:00
Place: Associations World, Foyer 1st floor

Thanks to @JoEgenolf and everyone involved in organising this tweetup. Another little bird tells me that  these tweeps will be there:  @techwriterkai @sarahokeefe @scottabel @redakteuse @umpff  @JoEgenolf @rahelab @kwiens @arockley @joegollner… any more?

C u there. For those who want to start tweeting right away, here’s the hash tag: #tcworld12

Atlassian User Group (AUG) Wiesbaden

The Atlassian User Group Wiesbaden meets on Thursday 25 October. The organiser is Sorin Stefan Nicolin, and he has invited me to present a session there too. I’m honoured, and I’m looking forward to meeting all the Atlassian customers and experts at the meeting.

How to plan a doc sprint

We’ve just held our fourth doc sprint. It was fun, rewarding and productive. This post is an update of one I posted a while ago, about planning a doc sprint. We’ve learned a bit since that first sprint, and I want to share those lessons with you.

Chocolate is inevitable

A doc sprint is an event that takes place over a short period of time (usually two or three days) in which people write documentation. In our case, we wrote code as well as words, because we were creating tutorials for developers. The doc sprinters may be in a room together, or collaborating online from various geographical locations.

For the August 2012 doc sprint, the Atlassian technical writers invited a number of developers and other technical communicators to join us in a three-day sprint, with the aim of producing some quality tutorials for Confluence plugin developers. (Atlassian is the company I work for. One of Atlassian’s products is Confluence wiki. Plugin developers are independent companies and individuals who build add-ons for Confluence. Some of those add-ons are available free of cost, others are commercial.)

What did we get up to during the doc sprint?

We shut ourselves up in a room and wrote like maniacs. We also ate chocolate, composed haikus when our brains needed a break, searched the documentation for golden tickets, and bombarded HipChat with inanities.

Seen on HipChat:

If there is ambient music, but everyone is wearing earphones, does it really make any sound?

Only if a tree is listening.

To synchronise with other sprinters, we held “remote standups” via webinars and video-conferencing. Why remote standups? Because we had 15-odd sprinters in Sydney, around 10 in San Francisco, one brave soul in Amsterdam, and 7 somewhere else entirely.

Update 12 September 2012: New post about the results of the sprint on the Atlassian blog: Atlassian doc sprint delivers 30 tutorials for Confluence 4.3.

When to start planning

Kicking off in Sydney

Early. We started planning in early June, for a sprint scheduled for mid August. That gave us three months to get our ducks in a row. I think we could have done it in two months, but certainly a sprint takes a lot of thinking and planning.

In our case, we wanted to  invite people to travel from various locations to our company offices, so we needed to give them plenty of warning. We also needed to get budgetary approval from management, and decide the focus of the sprint.

Involving your team and management

One of the greatest things about a doc sprint is how enthusiastic, generous and inventive people are when given an idea to play with. 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!

The people are the best part of a doc sprint.

Setting up a wish list of documents

Each doc sprint has a purpose: to develop a specific set of documentation. That purpose arises because the technical writing team and other members of the organisation know there’s a gap in the documentation.

We started by defining the focus of this particular sprint: tutorials on how to develop plugins for a specific version of the Confluence application.

I created a page on our intranet wiki, seeded it with a basic list of tutorials that I thought we needed and asked Atlassians for input. That gave us a good if somewhat unfocused list. Next I chatted to varous stakeholders 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 wish list 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 potential 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 wish list gave everyone a focus. Come the first morning of the sprint, many people dived right in without even waiting for the kickoff meeting.

Inviting people

Lively discussions

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, how many of us know 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 on the company blog, personal email messages to known members of the developer community, and messages in forums.

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 sprinters in our first sprint 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.

Learning from your previous sprint

If you’ve held a doc sprint before, you probably learned some lessons about what worked and what didn’t. It’s a good idea to put a task into your plan that tells you to go and look at those lessons learned, and see if you can apply any of them while planning the upcoming sprint. In particular, if you held a retrospective during the previous sprint, you can now go and read all the feedback and take advantage of the suggestions made. There’s more about retrospectives later in this post.

Scheduling some teaching sessions

This is something that arose from feedback given in the retrospective during a previous sprint. Sprinters are there to learn, as well as to contribute to the tutorials. In fact, they need to learn various aspects of the tools they’ll be using in order to do the work during the sprint. Some people will already be comfortable with the documentation platform, but not know the software development tools. Others will be cool with the code, but unfamiliar with the documentation tools and structure.

During our recent sprint, we ran a few short educational sessions every day. Each session lasted just ten minutes. The technical writers ran some of them, and an engineer ran others. They covered the structure of the documentation, documentation techniques such as content re-use, templates, the source repository, and best practices for writing tutorials. These sessions were well received, and were also a useful launching point for further discussion.

Templates and guidelines

Templates are extremely useful. They get people up and running quickly (reducing the fear factor) and they give a basic framework that is standard across all the tutorials. For this sprint, we updated our existing template for plugin tutorials.

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. The template is still a work in progress. For the next sprint, I’d like to split this template into three: one for beginner tutorials, one for intermediate and one for advanced.

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 means that would-be attendees can simply add themselves to the list and put their names down next to the tutorials they fancy. They can even add suggestions to the tutorial wish list. This helps people to feel involved immediately, long before the sprint starts.

We also published a schedule showing the activities day by day, for each location. At first the schedule and other information on the wiki was a bit bare. We fleshed it out as the sprint date drew closer.  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

Video conference with San Francisco sprinters

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.

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

• A chat room on HipChat. We had sprinters in various locations around the globe, and the chat room never had a moment’s rest!
• A series of webinars (online conference meetings) hosted by GoToMeeting.
• A Google Group, so that we could sent email messages to all sprinters. Actually, we have since decided that this is not such a useful channel. It was a misleading channel: people assumed (for good reason) that if they sent an email to the group, everyone would see it – but this was not true because only half the sprinters signed up to the Google Group. Also, there were too many email messages flying around. We’ll probably skip Google Groups next time.

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. At the same time as we ran the webinars, we also set up a video conference between the Atlassian offices in Sydney and San Franciso (at the start of the Sydney day)  and then Sydney and Amsterdam  (at the end of the Sydney day). That’s called burning the VC at both ends!

A lone sprinter in Amsterdam, seen from Sydney

For the daily webinar, we followed the pattern of standups (meetings held standing up, a mainstay of agile development) except that we were all sitting down. Each sprinter said what they had done so far, what they were planning to do next, and any roadblocks they had encountered. Just as in a standup, this led to useful interactions where one sprinter mentioned a problem, and another piped up with the solution they had found.

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 (Bitbucket). We keep the documents themselves on the Atlassian developer wiki. I made sure that each sprinter had the appropriate access rights to the wiki before we started.

Catering, venue and other practicalities

There are plenty 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 food. 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 buying the chocolate, because I knew I was likely to be in a tizzy and forget to do something vital. Think of the satisfaction you’ll have as you tick off each task.

Theme and fun

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

For our first doc sprint, 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 theme or a 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, we could perfect our ideas for fun stuff to do during the sprint.

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 Doc Sprint Hall of Fame.

Presentations (show and tell)

Serious stuff, preparing for the demo

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 demonstrating 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.

Retrospective

We also held a couple of retrospective sessions, to get feedback and suggestions from attendees, to hear what they thought went well and not so well, so that we can do things better next time. In Sydney and San Francisco, we met with all sprinters immediately after the presentations, to go through their feedback in detail. We used the wiki retrospective page to gather comments from all attendees scattered across the globe and collate them with the feedback we have gathered.

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 wish list, 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.

Afterwards

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 have created a Doc Sprint Hall of Fame, showing photographs taken during the sprint. We’ve also written a few blogs, on the Atlassian blog as well as here on ffeathers, mentioning the great work people have done in the four sprints we have held so far.

And… sprinters get a limited edition doc sprint T-shirt!

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 a technical writing review as soon as time allows.

More random tips

• Organise to have some experts in the room and on call, and make sure the sprinters know who they are. These experts will be technical writers and subject matter experts. In our case, we had some Confluence engineers on tap to answer questions.
• Get as many of the technical reviews done during the sprint as possible. After the sprint, people move back to their “real jobs” and it can be difficult for them to allocate time to the doc sprint aftermath.

There’s more in my book

I’ve recently published a book, called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about wikis and a whole lot more. There’s an entire chapter on doc sprints, with the following sections:

• What is a doc sprint? A description of the event and its aims.
• Some examples of doc sprints. The story of three Atlassian doc sprints and a list of sprints held by other organisations.
• Planning a doc sprint. A detailed guide to organising a doc sprint and using a wiki as the platform for the sprint.
• Fun. How to add some light relief.
• Demo and retrospective. A session where sprinters show what they have achieved and give feedback on the sprint itself.
• From an organiser’s point of view. Some tips about what it is like to organise a doc sprint.
• Aftermath. The things that need doing when the sprint is over.
• A doc sprint hall of fame. A good way of acknowledging the contributions of the sprinters.
• Unusual kinds of doc sprint. A reminder about innovation sprints, documentation blitz tests, and documentation blitzes.
• A retrospective on this chapter. Wrapping up the chapter.
• References. The websites, blog posts, and other references relevant to the content of this chapter.

The book also describes other types of special sprints that are useful for technical communicators in an agile environment especially.

In closing

Here’s a post from Swapnil Ogale, one of the external technical writers who joined us on the sprint: Experiencing the Atlassian Doc Sprint – Aug 2012.

For the brave amongst us: A big hairy task list for planning a doc sprint.

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.