Docs Team 3rd Quarter 2011 update

Hello from Jennifer and Ariane, your friendly Drupal Documentation Team co-leads! It’s time for a quarterly update on what’s happening in the Documentation Team—we've been working on some major restructuring of documentation and the Docs Team since our last update (June 28, 2011), and we'd like to get you up to date on our plans, and other events and news.

Docs restructuring

The big news for this quarter is that we are in the midst of some restructuring of the online Drupal documentation, as well as of the Documentation Team itself. Nothing has been completely settled yet, but here is an outline of our plans, reasoning, and links to more information and where you can get involved in the discussion.

Community documentation

The main issue we need to resolve is that the current online documentation on Drupal.org is way too overwhelming for one coordinator to manage. Having one coordinator is a single point of failure, and has led to several past Docs Team leaders getting burned out and leaving the post.

The current documentation has many features of a wiki: anyone can edit most of the pages, and anyone can add new pages... Yet we have found that potential documentation contributors are timid about actually editing and adding pages. So what we would like to do is turn responsibility over to the community as a whole, and make it abundantly clear that everyone can edit and contribute. The plans have been solidified on this issue: #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained., and if you'd like to help with the infrastructure changes (site building and module development), we are currently coordinating docs infrastructure work on http://groups.drupal.org/node/174499 . Follow-up changes to the infrastructure are being discussed on #1287784: Follow-ups to improve the community docs.

Curated documentation

Once we have those changes deployed, the next idea is to start a new section of documentation that will be more directly curated and maintained by the official Documentation Team leadership—and therefore, more limited in scope. The idea here is that careful decisions will be made about what are the "essentials" that belong in this documentation (which might be called "official documentation" or "user manual" or "curated documentation" or "essentials" or ...), and a small team will be responsible for maintaining the documentation. This idea has not been completely fleshed out yet; it's being discussed on issue #1291058: Discussion: Make a curated docs section/system if you'd like to join the discussion.

Outside documentation

Another idea that's in development is to make it possible to search external documentation—for instance, Drupal tutorials on blogs, and curriculum on Drupal company web sites. Lin Clark is currently exploring ideas for automatic collection of posts involving RDFa/microdata and SPARQL, and there will hopefully be more ideas and discussion about this in the next few months. Watch the Documentation Team on groups.drupal.org for updates!

API reference

We don't expect anything to change in the process, maintenance, or location of the API reference site on api.drupal.org. That process is actually working fine, and Jennifer is pleased to report that there have been many new contributors stepping up to submit patches lately. (Note: sprint coming up—see below!)

July - September events

Here are some events that the Documentation Team participated in during the third quarter of 2011:

• 
• At the end of August, many from the Docs Team were at DrupalCon London. We had BoFs ("Birds of a Feather" informal discussions) about DITA (a standard for documentation), the proposed new Help system for Drupal 8, and Lin Clark's ideas about using RDFa or microdata to build an index to documentation from Drupal Planet (see above).
• At DrupalCon, there was also a Core Conversation session about DITA and the new help system.

• 

• And of course we also had a very successful Documentation Sprint on the last day of the conference, with three tables of participants helping each other become knowledgeable documentation contributors. Thanks to all who participated!
• We are 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 find us on IRC, and we plan to continue with this schedule for the foreseeable future.

Upcoming API docs sprint

The API documentation on api.drupal.org has been improving slowly but surely over the past couple of years (I think/hope). But there are still quite a few areas where the documentation does not conform to the API documentation standards. Unfortunately, patches that do wholesale changes to documentation headers are disruptive to the ongoing improvements of the Drupal code, since they often require that many patches be "re-rolled" so that they will apply to the new code-base. So, we've been told several times that we needed to postpone these types of large-scale updates.

However, in early November, a patch is scheduled to go into Drupal 8 that will move all of the core Drupal files into a "core" directory. This will be a huge disruption, as every patch for Drupal 8 will need to be re-rolled. Because of this, it's a great time do other disruptive work, and we plan to have an API Documentation sprint just after that patch goes in, where we'll do a defined set of wholesale improvements to the in-code docs for Drupal 8. Mark your calendar—I'm hoping that we have lots of participants (including new API docs contributors) so the work for each person will be manageable!

Process, communication, and infrastructure milestones

Aside from the infrastructure and team reorganization mentioned above, there were some smaller initiatives in the Documentation Team this quarter:

• In July, Neil Drumm (drumm), with help from a few others, deployed a new feature to your Drupal.org user profile and Drupal.org company profile, aimed at recognizing documentation contributions: there is now a line in the History section of user profiles and the right sidebar of the new Marketplace company profile that says something like “Over 100 edits”, reflecting how many documentation page revisions you have made since joining Drupal.org. This is a small way of recognizing documentation contributions to the Drupal project.
• At DrupalCon Chicago, Dries suggested that in Drupal 8 development, each change would have to pass through a series of "gates" in order to be accepted, and Documentation was listed as one of his "gates", but it wasn’t defined what the gates really meant. So, a conversation was started with Jennifer, Angela Byron, and other members of the community, and in July, the Documentation gate standards were adopted. The adopted gates are listed on the gates page.
• In July, Angela Byron and Jennifer (along with many others) finalized two changes to the Drupal issue workflow: Issue Summaries and Change Notification nodes. With issue summaries, anyone can now edit the node body of any issue, to use the body as an Issue Summary, and we have a suggested issue summary template to use when filing or updating issues. With change notification nodes: for Drupal Core (and any other project that chooses to use them), after an issue is fixed, if the committed fix involves changes to the user interface or programming interface, a Change Notice node should be created to document the change. Then the Documentation Team, Coder module team, Examples module team, module developers, and theme developers can all visit http://drupal.org/list-changes (simple view) and http://drupal.org/list-change-updates (maintainer view) to find relevant changes that affect them or that need to be acted upon.
• Jennifer mentored Google Summer of Code student Tamás Demeter-Haludka (Yorirou) over the summer, who created the Conditional Text module. We expect to use this for the new Help system and probably the curated docs as well.

Next steps

If you're interested in helping with Drupal documentation:

That's all for now—we hope that your fall (or spring, if you're in the Southern Hemisphere) goes well, and we'll be in touch!