Agenda for a documentation event

A Documentation-focused contribution event 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 contribution events page for generic information on how to organize a contribution event; this page has information specific to Documentation events.

Who can participate?

Everyone! A documentation event 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 event is organized with tasks for all experience levels (see below).

Coordinators

Helpful skills and knowledge for event coordinators:

• Comfortable with the documentation projects and their issue queues (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). [This page currently needs work!]
• Familiar with the style guidelines.

Background and orientation

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

• Contribute to Documentation pages - the main starting point for any new Documentation contributor. [will need an update!]
• Chatting with the community on Slack
• Documentation policies, guidelines, and standards
• 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.
• 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 event, 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 event

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

• New Contributor Tasks - section with lots of tasks suitable to new contributors. There are tasks in the "Writers" and "Anyone" section that are good for documentation events. Also, telling people about this section is good, as they may be able to work on their own later, on different tasks. [Soon to be outdated]
• Browse the Contributor Guide by Task [in progress], or start with a Skill page like Technical Writing.
• Documentation Priorities - A list of what needs to be worked on, aimed at more experienced contributors who do not need step-by-step instructions. [Probably not up-to-date]
• 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. [This page currently needs work!]
• If you have programmer-writers at your event, 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.
• Issue queues to search:
  • Documentation issue queue - issues for the Drupal.org online documentation.
  • User Guide issue queue -- issues for the Drupal User Guide
  • 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 event that are not strong writers of English, you might suggest that they do technical reviews rather than writing tasks.