Documentation sprints

Last updated March 26, 2012.

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.

See the main organizing sprints page for generic information on how to organize a sprint; this page has information specific to Documentation sprints.

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

Coordinators

Helpful skills and knowledge for sprint coordinators:

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

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.

Finding tasks for your sprint

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

• New Contributor Tasks - section with lots of tasks suitable to new contributors
• 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 -- 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.