By arianek on

Hello from your friendly neighbourhood Drupal Docs co-leads!

It's been an action-packed December in the Drupal Docs world. Drupal 7 is poised to be released in the next few weeks, and we’ve been focusing accordingly on getting the Drupal 7 documentation ready. In addition, Addison Berry (outgoing docs lead) used the last chunk of her Knight Foundation grant to fund a planning meeting and sprint in Vancouver in early December. At the planning meeting, the incoming and outgoing documentation team leadership got together with a few Drupal.org redesign and infrastructure people to make plans and set realistic goals for the next year. We followed this up with an all-day documentation sprint that was open to the general documentation community, with participants both in Vancouver and around the world in IRC. Thanks to all who participated!

One of our goals as new documentation team leaders is to post regular status updates, in order to communicate our goals and plans, what we’ve been doing, and what we’re hoping to accomplish with your help. This will be the first of our quarterly updates, and the sections below outline some of the short-term and longer-term priorities of the Documentation Team. Since this is our first official communication, we have a lot to catch up on!

Immediate goal: Drupal 7 Docs

With Drupal 7's official release date just around the corner (in early January), and the in-code help and API docs in pretty good shape, our main short-term priority for the Documentation team is to make sure that the essential sections of the online documentation are updated for Drupal 7. Our main efforts have been directed towards the following issues; if you are able to help review and update any sections, please add a comment to that issue (or assign it to yourself), and then when you finish the review, add a comment with your review results (and unassign from yourself if you are done working on it).

Mostly done

  • The Drupal 7 Install guide: Updating the main install guide, and "Quick install" guide for experts. In addition, we've now got the beginnings of a Quick install for beginners version up, which is just about ready. This version will cover the basics for anyone who is on standard shared hosting, using FTP rather than command line. You can help by testing the Install guide next time you do a Drupal 7 install, and noting any issues on #538054: Review and update the Installation guide.
  • Core module handbook pages: Last year, the Documentation team made a short, directed effort to improve the module help pages in the Drupal core code (the online help you can see inside a Drupal installation). At that time, we made sure that each core Drupal module had at least a stub page in the Drupal.org online documentation as well. A lot of the core module handbook pages were then written and/or updated at the sprint and Core Dev summit at DrupalCon Copenhagen and the sprint at the PNW Drupal Summit (thank you to everyone who helped out!), but there is still some final polishing needed. You can help by doing final reviews on any of the core module pages for modules that were already in core, or for new core modules and noting any small errors in those main issues (or filing new issues in the Documentation queue for any larger problems).

Needs work!

  • The D6 to D7 Upgrade guide (still in the docs initiatives book while in-progress): This has been in the works for over a year, and has slowly been coming together as the upgrade path has been getting completed. A dedicated group has been chipping away at this, and now that we’re in the later stages of the development cycle, it'll be time to do a final push over the next few weeks to get solid documentation for all of the completed upgrade path. We will want to include instructions for modules that have now been merged into core, such as how to do the CCK migration required to move your custom field content into core, and the equivalents for all other previously contributed modules that are now in core. Some of this will have to wait until the related migration helper modules are ready. (See issue #536854: Review and test the upgrade guide for Drupal 7.)
  • Theming guide: Most of the theming guide has not been updated with Drupal 7 specific information. Any existing pages should have any information unique to Drupal 7 added to them, and we may need to add a few new pages for any completely new functionality. (See issue #740194: Update theming guide for Drupal 7 if you want to help out!)
  • Module developers guide: Developing Drupal 7 modules is fairly similar to developing Drupal 6 modules. However, a lot of the hooks have changed, and several core APIs have been completely overhauled. The guides for some of the APIs have been updated for Drupal 7 (notably, the completely-redone Database API), but there is still work to be done. You can help by:

If you would like to work on any of the above API related issues and are a new contributor, you might want to read the guide to updating API documentation. If you are new at working on the online documentation, please refer to the Online documentation style guide for style and language guidelines. And you can always ping either of us (Jennifer aka. jhodgdon or Ariane aka. arianek) on IRC in the #drupal-docs channel for help.

Longer-term goals

Besides the immediate goal of improving the Drupal 7 documentation (see above), the Documentation Team also has made some longer-term goals in the area of structure, team building, organization, and processes. Before the December planning meeting, we solicited input from the entire documentation team, and we discussed these ideas and more at our meeting. The following are the key areas of work we've chosen to focus on for the coming months.

Team building and sprints

As co-leads, one of the things we are most keenly aware of is that we cannot write all the documentation for Drupal ourselves. Accordingly, one of our highest priorities is to recruit, motivate, and retain a team of contributors to Drupal documentation. This goal is no less important than our more concrete documentation and infrastructure goals, but is in some ways much more difficult, at least for us (we may be good at writing documentation and very organized, but we aren’t necessarily experts in how to manage and motivate an open-source team).

We've identified some specific areas in which we can improve:

  • Communication: We will be working on clearly communicating areas that need work to current and potential documentation team members (as well as the larger Drupal community), along with what you can do to help. We'll also be working on keeping everyone up to date on what the documentation team has been doing and plans to do in the near-term and longer-term. Part of our communication strategy is regular (roughly quarterly) Drupal.org front-page posts such as this one; other lines of communication include Twitter (@drupaldocs), the Documentation Team group on groups.drupal.org, using the #drupal-docs channel on IRC (to keep our work transparent and easy for others to give input on), and keeping the Contribute to Documentation pages on Drupal.org up to date.
  • Sprints: We have found that many potential new documentation contributors are intimidated by the issue queue and other processes we use in the Drupal community. Documentation sprints are a great way to introduce new contributors to our processes and remove the barriers to contributing, but obviously we aren't able to attend every sprint. As a means to support other sprinters and event organizers, we plan to set up a clear How-To guide, with the goal of empowering all documentation contributors to host sprints at local and regional Drupal events.
  • Clarifying needs and methods: Along the lines of removing barriers, we are also thinking about making a video on how to contribute to documentation—please comment on that issue or the planning wiki it references if you have ideas about what should be included, or if you would like to work on creating the video! In conjunction with that, we will continue to improve the How to contribute to documentation section of the Contribute to Documentation guide. Please add your suggestions to the above issue.

Documentation structure, organization, and processes

In addition to team building, at our Vancouver planning meeting we discussed several areas where we would like to improve in the structure and organization of the documentation itself, as well as process improvements we would like to make. These are the specific improvements we'll be working on:

  • Out-dated content: In the past, we have been reluctant to purge content that is no longer needed, and have instead moved it to the Archive book, where it was unfortunately still available in internal and external (e.g., Google) search results. We have now unpublished everything in the Archive book, and plan to automatically unpublish pages that are moved there in the future.
  • Consolidating duplicate/similar content: We also have a lot of duplicate content in the online documentation. Over the next year or so, we plan to make infrastructure improvements to address two key reasons for this: (a) The Book module only allows a page to be part of a single book hierarchy, so sometimes we have the same content in two places in the online documentation. Instead, we want to be able to create multiple “maps" (outlines) of Drupal.org documentation pages, including user-supplied maps. (b) We have many pages that have been copied and lightly edited in order to accommodate different versions of Drupal. It would be preferable to have “conditional text" ability, where we could use the same page for multiple Drupal (or module) versions, but have portions of the page designated as pertinent to a particular version.
  • Clear, concise documentation: Once we have these two infrastructure improvements in place, our goal would be to gradually move towards having each page in the online documentation be small, unique, covering one atomic topic, and with an appropriate title. We would also want to clean the “table of contents" types of pages out of the documentation, as they would not be necessary. Obviously, this will take some work and we'll be looking for a team effort here! We’ll keep you posted on progress of the infrastructure changes that will be a precursor to this work.
  • Comments: People often comment on Drupal.org documentation pages. The comments are rarely, if ever, a good idea—we would prefer that people edit pages directly or file an issue in the Documentation issue queue if there are changes needed (or alternately to use IRC or the support forums if they are looking for help). We have begun the process of turning off comments on the documentation, and adding a link to each page that will help people file an issue instead. Comments will be locked but still visible, and gradually we will be reviewing and deleting them after incorporating their information into the documentation (if necessary). You can start working on the comment-incorporation task now; it's a great way to get familiar with working with the online documentation!
  • Cross-referencing: One of the issues people have on Drupal.org is finding the appropriate documentation and knowing its status. Unpublishing the Archived documentation should help search results (see above), but we also plan to add some new linking features to documentation. First, we would like to have each documentation page reference the project(s) to which it refers. This would also make it possible for each project page to display an automatically-generated list of its documentation. Second, we would like to have each Documentation issue reference the book page(s) to which it refers, which would make it possible for each book page to display an automatically-generated list of the open issues that have been filed against it.
  • Page status tags: We have recently updated the page status taxonomy and the Documentation issue queue components, so that it should be clearer how to mark a page as needing work. In conjunction with that, there is an exciting (and practical!) new documentation management view (log in to see it), which you can use to find pages to work on (filter by status, number of comments, etc.).
  • Editing privileges: We need to make some adjustments to input formats and privileges in the documentation pages. Issue: #995354: Docs format and Docs role - figure out what to do -- comments welcome.
  • Other infrastructure improvements: We discussed many other ideas at our meeting, and selected a few other structural improvements to work on in the near to medium term. If you’re interested, you can follow progress by searching for issues tagged “docsyvr2010" across projects. Any input and patches you wish to supply on those issues would be welcome! We are also working on some improvements to the functionality of api.drupal.org; you can follow (and contribute to) the progress of this initiative in the API module issue queue.

Big Vancouver docs sprint!

The Docs Team meeting where we discussed all of these issues was followed by an all-day sprint in Vancouver and on IRC. We had a great turn out, and got a lot of work done on both the handbook (in particular, the install and upgrade guides), as well as some of the infrastructure features we'd discussed the previous day.

We were lucky enough to have a bunch of docs enthusiasts from other teams in the Drupal community fly to Vancouver (thanks to the remnants of Addison's Knight Foundation grant) to join us and a whole bunch of local Vancouver user group members for some excellent sprinting!

The core developers and infrastructure team members who were able to join us spent the day working mainly on new features for Drupal.org, and the API module. Several local Vancouver Drupallers also worked on handbook docs, starting the new Quick Install guide and reviewing of some of the handbook structure and organization.

Special thanks to The Jibe for hosting both this and the PNW Summit sprints, and to Ben and his kids for feeding us delicious chocolate chip cookies fresh out of the oven!

And on that note...

You can see it's been a busy fall here in Docs land! We want to keep this momentum going to get the Drupal 7 documentation completed, and then to keep working on improvements to the Documentation infrastructure, particularly in the spring after DrupalCon Chicago. If you'd like to work on Drupal's documentation (and we know you do!) read more about how to get involved, and join the g.d.o Docs Team group to stay up to date.

Till next time!

- Jennifer and Ariane