Panda-Media

Hello from Jennifer, your friendly Drupal Documentation Team leader! It’s time for a quarterly update on what’s happening in the Documentation team. As you probably heard, Ariane's role in the Documentation Team has changed, and she is no longer my co-leader (sob!), so I'm looking for a new deputy leader or co-leader (watch http://groups.drupal.org/documentation-team for details). Here's what Ariane and I oversaw in the Documentation Team at the end of 2011, with a look forward to 2012.

September - December Events

• The Documentation Team is holding weekly ”Documentation Office Hours"—one-hour IRC meetings on Tuesday afternoon (North American time), open to anyone for questions and discussions about contributing to documentation. It seems like it's been very helpful to have a definite time when people can get together on IRC, and we plan to continue with this schedule for the foreseeable future.
• In October, I was able to attend the Friday of the Bay Area Drupal Camp (BADCamp). We had a small documentation sprint, and a few people got up to speed on writing API documentation patches. Also, Kathy (kathyh) spent the afternoon writing a new guide for novice contributors to Drupal core, based on her experiences as a novice contributor -- thanks Kathy!
• We started an API documentation cleanup sprint in November, to bring the Drupal 8 and Drupal 7 core API documentation much more in line with our documentation standards (see meta issue). My big hopes for this sprint:
  1. Lots of documentation cleanup -- YES! The sprint is not finished yet, but MUCH more of our documentation is up to standards. In the process, a lot of weird wording has been fixed, and the documentation is clearer and easier to scan. Also, people usually copy/paste an existing documentation header when creating new documentation (or at least use an existing one as a model), so the more we clean up existing documentation, the better future documentation is likely to be.
  2. Lots of participants -- YES! My hope was that some people new to contributing to Drupal API documentation would see the sprint as a good way to get up to speed on making Drupal patches, and on the API documentation standards. And they did!
  3. Build a Drupal Core Documentation Issue Queue Squad -- Yes! Part-way through the sprint, I put out a call for participants to start reviewing other people's patches as well as creating patches, and they did! And now some of them are helping out with the "documentation" component of the Drupal Core issue queue -- watching for new issues, making patches, reviewing other's patches -- which was my secret hope all along (for the last several years, it's been a rather lonely issue queue, since I have had to either write or review nearly every patch in it -- that model is not sustainable, so I'm really happy to have some company).

  Thanks to xjm, xenophyle, sven.lauer, Lars Toomre, aenw, rc_100, jn2, aspilicious, chris.leversuch, barlantz, synth3tk, agentrickard, ... and probably more who joined after I made this list -- sorry if I forgot your name! This sprint is still going on, so if you’d like to participate, visit the meta issue, which has full instructions (novice contributors welcome!).

Documentation Infrastructure Updates

The last quarter of 2011 saw some changes to Drupal.org that are quite beneficial to Documentation writers, editors, and users -- and more are on the way! Here's a list:

• After much discussion, we came up with an overview plan for how to restructure Drupal documentation into Community, Curated/Help, API, and External Index documentation in September of 2011 (see http://groups.drupal.org/node/175174). During this quarter, we started putting the transformation into place. The first step was a mammoth design issue (190+ comments!) for the Community Documentation (which is a rename of the existing Documentation on Drupal.org in the early fall. The results of that process are partly deployed (read on for details), and more are coming soon.
• One of the main conclusions of the mammoth design issue was that one of the biggest barriers we see to people contributing to the online documentation on drupal.org is reluctance to click the Edit button -- people just aren’t sure whether it’s really OK. So, the redesign of the documentation pages that was deployed in January 2012 included:
  • The existing Documentation pages on Drupal.org have now been renamed "Community Documentation", to reduce the perception that you have to be part of the "documentation team" in order to edit.
  • The page status and other meta-information has been moved to the sidebar
  • At the top, there’s a list of several people who have edited the page, with a clear invitation for you to edit the page.

  Hopefully these changes will help overcome this barrier -- we’ll see!

• We added two taxonomies to Drupal.org documentation pages: keywords and experience level. Right now, they have only been selected on a few pages, but hopefully going forward the keywords will help people find related pages, and the level will help set expectations for the knowledge level needed to understand the page.
• Everyone can now upload images to Drupal.org (issue). Angie/webchick and Daniel/sun made a module that made it safe for people to upload images, and it was deployed in October of 2011. There are followup plans to remove the restrictive Documentation input format from most pages (i.e., to unlock those pages), and to get rid of the Documentation Admin role -- no one should need this role now, since everyone can now upload images and use tables using the default Filtered HTML input format.
• BUEditor was deployed on Drupal.org in October of 2011. This module adds a small toolbar with HTML shortcuts to rich text fields (documentation node bodies, comments, etc.). While this falls short of being a WYSIWYG editor, due to security concerns with existing WYSIWYG modules, this is probably as close as we'll get for the foreseeable future.
• Neil Drumm and Jennifer spearheaded an effort to commit and deploy some updates to the software for api.drupal.org in November 2011 -- thanks to aenw, solotandem, and Greyside for contributing patches for that deployment! If you would like to work on the API module, check out the issue queue (http://drupal.org/project/issues/api) or find jhodgdon in IRC to get oriented. A new deployment to api.drupal.org should be coming shortly, with a lot of user interface updates and more new contributors. Stay tuned!

Next Steps

If you're interested in helping with Drupal documentation:

• New contributors: start at http://drupal.org/contribute/documentation to learn all about contributing to documentation, or come to the weekly office hours (see Events section above) to ask questions and get started. (Jennifer recently edited this whole section, so it should be up to date.)
• Drupal Documentation announcements, discussions, and events are posted on http://groups.drupal.org/documentation-team and on Twitter (@drupaldocs).
• API documentation cleanup sprint (for programmer-documenters): http://drupal.org/node/1310084
• Work on the API module: http://drupal.org/project/issues/api -- the issues are all prioritized, so look for ones with priority "major" for the current priorities. Or pick up any issue you're interested in -- we won't say No to a good patch.