Documentation sprints

Last updated September 9, 2011.

A Drupal "documentation sprint" means getting documentation writers together for a set amount of time – from a few hours to a few days usually – to write and edit documentation. We choose to work on documentation in a sprint format because:

• It's fun - sometimes it is nice to have some camaraderie while working.
• It's satisfying - the group can see the progress that was made at the end of the sprint.
• It's a good way to get a focused task done (though some sprints are more general and some are more focused).
• Participants can get their questions answered immediately instead of waiting for an answer in an issue queue.
• Participants can learn from each other.

Documentation sprints can be in-person at an event (local user group meeting, regional camp or open-source festival, DrupalCon), or on-line on IRC; many are also a combination of in-person and on-line.

Jump down to the bottom of this page for a quick checklist for hosting a sprint.

Who can participate?

Everyone! A documentation sprint does not need to be run or attended by only experienced contributors to Drupal documentation. Anyone with a desire to help make Drupal documentation better can take part, as long as the sprint is organized with tasks for all experience levels (see below).

How do I find a sprint to join?

You can find a list of sprints taking place around the world on the documentation team group page on groups.drupal.org, or by searching the groups.drupal.org event page for a sprint. Keep in mind that even if you can't get to a sprint in person, you may be able to join in on-line -- contact the organizers or post a comment on the event page to find out for sure.

If you don't find a sprint to join, you can organize your own! (See below.)

Informal sprints with IRC

If you have an hour or two to spare, you can always do your own mini-sprint -- and if you would like some camaraderie while you're working on documentation, join the #drupal-docs IRC channel, which is always on (though not always active). If you are not familiar with IRC, check the Drupal IRC page for more information. The Contribute to Documentation section is the best place to get oriented, if you're new to documentation.

Planning your own documentation sprint

If you'd like to host a documentation sprint (and we encourage you to do so!), this section (along with the following section on what to do at a sprint) will help you to plan a successful sprint.

Venue and Supplies

The venue for your sprint can be either a physical location, online in the #drupal-docs IRC channel, or both. Possible locations:

• Library meeting room
• Business conference or board room
• University classroom or computer lab
• Board or meeting room of a company
• Someone's living room, if it is a very small sprint

Considerations and things to have on hand for an in-person sprint:

• Wi-fi access
• Enough chairs and tables for everyone - preferably tables where about 6-10 people can sit and collaborate
• Whiteboard or easel pad, markers
• Cards or paper for doodles/sketches, pens and pencils (possibly colored)
• Sprint info sheets (document attached at the bottom of this page) - you can fill them out ahead of time, or let group leaders within the sprint fill them out.
• Name tags, and perhaps some kind of sticker or special tag for coordinators (for large sprints)
• Sticky notes: you can put issue numbers or tasks on sticky notes on a board, and people can go pick one up to claim it as their task.
• Snacks - healthy and non-healthy
• Periodic meals (delivered or nearby) if your sprint goes more than a few hours

Publicity

Announce your sprint by posting an "Event" on groups.drupal.org. When creating a content item on groups.drupal.org, you can choose which groups to post it in. A good strategy is to post your sprint in the group(s) nearest the location of the sprint, and cross-post to the Documentation Team group as well. If you're not a member, you'll need to join the Documentation Team group first.

In your announcement, list:

• Time/date
• Location and directions
• Attractions (free food, Drupal rock stars in attendance, etc.)
• Focus, if there is one
• Qualifications needed for participating, or who is invited to attend
• Whether there will be IRC participation
• Etiquette statement (see People section below)

You may also want to post your sprint on other calendars (outside of groups.drupal.org, such as CraigsList, etc.). If the event is large and formal, the marketing resources section may be helpful (that's also where to find the Druplicon logo).

People: Groups, coordinators, etiquette

It will be helpful to recruit some experienced documentation contributors to help with the sprint. We normally suggest having about one "cat herder" (coordinator) for each 10 people or so, to be there to answer questions (or find answers), get new people who show up going, keep things moving, etc. Helpful skills and knowledge:

• Comfortable with the Docs issue queue (can lead others in issue browsing/searching, tags, posting, and commenting).
• Comfortable with the Documentation management page (can lead others in using it to find a page to work on).
• Familiar with the style guidelines.

Sprint info sheets (attached document at the bottom of the page) can be useful for defining tasks for the sprint, if you want a formal structure. You could fill them out ahead of time, or allow groups to form organically, and provide sheets that each group can fill out as they define their tasks.

Make sure there is also someone on hand who can answer practical questions, such as "what's the WiFi password?" and "where's the bathroom?". Or better yet, write this information on your white board at the start of the sprint. In a large sprint with many new contributors, it may also be helpful to have a designated person who can help new people get set up with IRC, find the style guidelines, get oriented, etc.

You might also want to orient participants on etiquette. Suggested statement:

Please respect the fact that everyone is at the sprint to get some work done, which in practical terms means not being too loud so that everyone can focus, and not interrupting anyone who does not wish to be interrupted. However, don't let that idea stand in the way of discussing work or enjoying the camaraderie of working on documentation in a sprint setting.

Background and orientation

The following background information should be useful for orienting documentation contributors at your sprint:

• Contribute to Documentation pages - the main starting point for any new Documentation contributor.
• Guide to Drupal IRC
• Guidelines list - a list of links to various style, structure, and other guidelines pages, including the overall Drupal.org style guides section.
• Contributors may want to add the Documentation Team Links block to their Dashboard. To do this, click on Your Dashboard in the top navigation, and click on "add block".
• Participants may need to set up a local web server, in order to install local test Drupal sites to review documentation, or to test changes to Drupal core user interface text. People working on patches to Drupal core (API docs or user interface text) will also need to learn about the Git version control system, and all contributors may need a text editor or other development tools.
• Documentation management page - allows you to find documentation pages that need attention.
• If there's a chance that multiple people might be working on the same page or issue, follow this procedure:
  1. If you are starting to edit a page, put the following at the top: "This page is currently being edited by [your name]", and save the page. Make sure you remove that text when you are done.
  2. If you are unsure of your changes on a page, file an issue when you are done, asking for a review.
  3. If you are starting to work on an issue, begin by adding a comment stating what you plan to do, and assign the issue to yourself. When you are finished, go back to the issue and comment again about what you did, change the issue status to "needs review" or "fixed" if appropriate, and un-assign the issue.
  4. Anything pertinent to the issue that you discover or think of, be sure to put it in a comment on the issue so no one has to go through the same thought process again. Please try to provide constructive criticism rather than writing statements that seem more like personal attacks.
• Especially if there are any connectivity issues at the sprint, it's advisable to do most of your editing in an external text editor (such as NotePad or an email program). From that source, update the drupal.org site occasionally.

Tasks for sprints

A sprint can be focused on a definite documentation task (or a specific group of tasks), or it can be a more general "Let's get together and work on documentation" sprint. In either case, it helps to do some planning ahead of time, so that when participants arrive, you can quickly get them going on an actual task. You'll need to figure out whether your sprint is open to all contributors or just a subset (e.g., people with certain background, interests, or skill levels), and make sure the tasks you have planned are appropriate for the people you have invited to join.

Keeping track of your sprint tasks

Sprint info sheets (attached document at the bottom of the page) can be useful for keeping track of what tasks you have planned. Another useful way to keep track of your tasks is to tag issues. To do this:

• Make up a tag for your sprint, such as "sea-docs-jun11".
• About a week before the sprint, find issues in the Documentation issue queue or documentation-related issues in the Drupal core issue queue that you want your sprint to work on.
• Add your tag to each issue, along with a comment like "Working on this issue in the June 22, 2011 Seattle Docs Sprint", so that others will know to leave that issue for your sprint participants. Including the date of the sprint is helpful, so that if the issue doesn't get resolved, someone else can know it is OK to work on it after the sprint is over.
• On the day of the sprint, post the issue tag and/or a link to an issue search for that tag at your sprint.

Finding tasks for your sprint

The following ideas may help you to find tasks appropriate to your sprint:

• The How to contribute to documentation section lists various tasks that always need to be done for documentation, including maintenance tasks, editing documentation embedded in Drupal, and working on API documentation.
• Within that, the Documentation maintenance tasks page lists a number of tasks that always need to be done for Drupal documentation. In particular, the Bring a friend to docs month page describes how to ease new documentation contributor into doing style and technical reviews (one of the on-going maintenance tasks).
• You can also use the Documentation management view to find pages that need attention. Or you can just have people show up and find pages themselves (see the quick checklist for hosting a sprint section below for this method) -- this requires less task planning.
• One thing that's always helpful, if you have people at your sprint that are new to Drupal, is to have them review documentation. For this task, have the beginner try to follow the instructions in a documentation page or section, and ideally, have a second person watch and record where they had trouble because the documentation was misleading, unclear, incomplete, or inaccurate.
• If you have programmer-writers at your sprint, there are always plenty of API documentation issues to work on. Keep in mind that new API doc contributors may need help setting up their development environment and learning how to make patches. There's a guide on the Updating API documentation page.
• The Documentation group page usually has a recent post listing monthly documentation priorities, and the documentation team leaders also try to keep the Current documentation priorities page up-to-date
• Issue queues to search:
  • Documentation issue queue - issues for the Drupal.org online documentation. The Documentation sub-groups page also lists some more targeted documentation issue queue searches.
  • Programmer-writers: queue of issues in Drupal in the "documentation" component (mostly issues where someone has noticed that there is a problem with some function/API documentation); queue of issues in Drupal tagged with "Needs Documentation" (issues where someone has modified the core PHP files of Drupal, and the result is that some documentation also needs to be updated).
  • Text within Drupal core: queue of issues in Drupal tagged with "ui-text", queue of issues in Drupal in the "user interface text" component, and queue of issues in Drupal tagged with "Help text"

Other considerations for finding tasks

• Look for issues whose status is "active" or "needs work" if you want to find writing tasks. Look for "needs review" issues if you want reviewing tasks (an excellent place for new contributors to start, and a vitally important part of the process).
• Tasks related to the latest in-development version of Drupal are a priority over issues on older versions. Bug reports are a priority over feature requests. Critical issues are a priority over normal issues, which are a priority over minor issues.
• If you will have some people at your sprint that are not strong writers of English, you might suggest that they do technical reviews rather than writing tasks.

Quick checklist for hosting a sprint

If you're putting together a documentation sprint at the last minute, for instance at a regional Drupal camp, here's a quick checklist (read the full guide above):

1. Get a room with WiFi and a table (or tables) to sit around (it's nice if people can see each other rather than a classroom-style room).
2. Announce the sprint, and make it clear everyone is welcome.
3. Appoint a "cat herder" - someone to get people started. (An experienced doc sprint herder can probably herd about 30 people. A less experienced one might be OK with about 10 people. But at least have one.)
4. As people come, point them to http://drupal.org/documentation/manage (they will need to log in to see it) and have them find a page to work on. For new contributors, here are some starting places:
   • Filter for Page Status "Needs Copy/Style Review" (pages needing some copy editing). Have them find a page, click Edit, and fix it up (they might look at revision log to see if there are comments about what needs to be revised). Point out the style guide: http://drupal.org/style-guide
   • Filter for Comment Count greater than or equal to 1 (pages needing comments rolled in). The cat herder should read the guide on how to roll comments: http://drupal.org/node/135589 -- basically figure out if the comments have merit, and if so, incorporate into the text of the page, then file an issue to have the comments deleted)

   Stress that if they can see an Edit button on a page, they are encouraged to edit the page, if it needs editing. :)

5. As people get bored with style edits and rolling comments, point them towards the Documentation issue queue to find more interesting things to work on: http://drupal.org/project/issues/documentation -- or they can go back to the Management page and filter for "needs technical review", "needs updating", etc.
6. Try to get people to help each other and above all, feel welcome, feel appreciated, and have fun!