Docs Team spring 2011 update

Hello from Jennifer and Ariane, your friendly Drupal Documentation Team co-leads! It’s time for another quarterly update on what’s happening in the Documentation Team—a lot has been going on since our last update (December 24, 2010), and we’d like to take this time to review the past quarter, talk a bit about the future, and let you know how to get involved! (Be sure not to miss the info at the very end about the April 2011 month-long documentation sprint priorities!)

Long-term goals and vision

People have been asking us about the long-term goals and vision of the Documentation Team lately. We’ve outlined some goals for the next year or so, but as of yet, we haven’t really articulated anything out farther than that. Rest assured, we will be thinking about longer-term goals and vision soon, but as new Documentation Team leads, we are currently still trying to get the basics taken care of and assess where we are and what resources we have for changing directions. That said, we do have some overarching goals:

• Make the documentation more complete and more accurate.
• Make it easier for users of all levels to navigate the documentation.
• Facilitate documentation work, so more people can help and those who are already helping want to continue.

If you have ideas about what our longer-term goals and vision should be, please start a discussion on http://groups.drupal.org/documentation-team - we’d love to hear your ideas!

January-March 2011 Docs Team happenings

Events

The Docs team participated in several events during January-March 2011.

Core conversations and sessions at DrupalCon Chicago

• We led a very productive discussion on a new help system for Drupal 8, which spanned a “Core Conversation” session and two Birds of a Feather sessions, and which will hopefully result in an improved Help module for Drupal 8 core (see Priorities section below for more information).
• We also presented a more general session on the state of the Documentation and Docs Team, and a call for participation/contribution. The video from the session should be posted on Archive.org soon. Several people contacted us afterwards to find out how to get involved (besides the people who attended the sprint—more information on that below).

Documentation sprint at DrupalCon Chicago

So many docs sprinters! Ariane led the main sprint in person in Chicago, while Jennifer joined via IRC from Seattle to lead the API docs sprinters. We peaked at 45 people in early afternoon, and there were certainly more attendees throughout the course of the day. Many commented and/or signed up on http://groups.drupal.org/node/132194 to show their attendance, and here are some highlights:

• drewish helped get several new people up to speed on contributing to API documentation. His quote of the day: “Docs are so much more fun. You can actually finish a patch in under an hour” (as compared to doing core code patches). He asked Jennifer not to spread the word about this, so he could keep all the fun and credit to himself, but she ignored that part. :) jeffschuler also worked on API docs, and drumm came by for a bit to answer some questions about API module.
• carolyn, liberatr, rootwork, and a pile of other folks worked on the theme docs! They are brave souls, and actually got a bunch of the theme docs updated with Drupal 7 information.
• wilbyr and greggmarshall started rearranging some distribution docs to get a solid base for this growing.
• gravelpot, mikechase, and some others worked on reviewing the Drupal 6 to 7 upgrade docs (the core upgrade docs are now finished!)
• jjkd, skjalf, bmadore, and others got us closer to having all of the Drupal 7 core module docs updated.



• itangalo, kvantomme, and eric_sea worked on planning and prototyping some of the new documentation and help system infrastructure improvements.
• chachasikes did some visualizations and diagrams of data migration methods.
• And more... we were so busy we can’t remember it all!

Thanks to all who participated in the sprint!!!

Other events

Several groups held smaller, but still mighty, documentation sprints, such as one led by bmadore and company on a bus trip from Minneapolis to DrupalCon.

And there was a lot of informal docs sprinting in the Sheraton lobby all through the week as well!

Documentation milestones

Here are a few significant pieces of documentation that were written or improved during the first quarter of 2011:

• Melissa Anderson (eliza411) led a team creating documentation for Git, and they rolled out the docs in time for the Git migration (when Drupal.org changed from using CVS to Git for source code revision control).
• The Install guide for Drupal 7 was completed.
• The Drupal 7 Upgrade guide was finished.
• Documentation pages for all the new D7 core modules were completed, and we’re also getting close to having all the old core module pages from D6 updated with D7 information.

Process, communication, and infrastructure milestones

Here are some things the Documentation team did to improve processes, communication, and infrastructure over the last few months:

• Made a Current Priorities page, which we will try to keep up to date with a list of current documentation priorities that anyone can join in on.
• Updated the Documentation section in Community Initiatives, which we plan to keep up to date with the status of more long-term initiatives.
• Did some editing in the Contribute to Docs section to make it easier for new people to get going.
• Made some infrastructure improvements:
  • The Drupal.org online documentation used to be known as the “Handbook”, before the Drupal.org redesign. Accordingly, there were a number of page aliases that started with “/handbook”, including the main documentation landing page. These were all changed to start with “/documentation”, with permanent redirects (issue: #995310: Update aliases - /handbook to /documentation). Kieran Lal reported at DrupalCon that since making this change (which impacted the documentation SEO significantly), the page views for the online docs have shot up like crazy!
  • The “Help with documentation” block that appears on the right side of the main Documentation page was improved (issue: #995334: Improve the Help with Doc block ).
  • There is a new “Docs infrastructure” component for the Documentation project issue queue, where we’ll be discussing further documentation infrastructure issues.
• We now have topic-based subgroups in the Docs Team, and standardized tags for the Documentation project issue queue. If you’re interested in documentation for a particular topic, please sign up at: http://groups.drupal.org/node/125669, and find which tags are tracking those issues.
• Jennifer did a Drupal Dojo screencast on using issue queues, to help demystify them.

Priorities and initiatives: Next steps for YOU!

Here is what we’d like to concentrate on for the near future in the Documentation Team:

• If you are a new contributor to Drupal documentation, start with the Contributing to Documentation guide.
• You can always check the Current Priorities page to keep up to date with current short-term priorities, http://drupal.org/community-initiatives/documentation for longer-term projects, and http://drupal.org/node/1006924 for Drupal.org improvement projects (some of which impact documentation).
• Another way to find things to work on is to filter for critical issues in the documentation issue queues.
• We are working on a new help system for Drupal 8 that will make it easier for Docs team people to edit the inline help in Drupal, incorporate DITA principles, and be flexible enough for both Core and Contrib (see http://drupal.org/node/1095012). There are several pieces of it that need to be done (in code), so if you’re a coder and would like to help out, contact Jennifer.
• Drupal 8: Dries mentioned in his keynote address at DrupalCon Chicago that there will be a Documentation “Gateway” that all Drupal Core initiatives will have to go through before they are added to Drupal. We’ll be working with Dries on defining what that means, communicating that to the core developers and the Documentation Team, and mobilizing the Documentation Team to help the core developers implement the plan.
• Ariane plans to do a pilot of running agile sprints (not to be confused with documentation sprints where we get together in a room and work on documentation for a day) for the online docs work. More information about that is posted on the Docs Team group: http://groups.drupal.org/node/134909, and the April sprint priorities are in place, so if you are looking for something to help with and have some time this month, please jump in on the April sprint so we can finish up some high priority Drupal 7 documentation!

That's all for this update, hope you all have a fantastic and documentation-filled spring!