OBSOLETE - Documentation Team Longer-Term Goals

This page is obsolete!

This page (and section) are obsolete. As of spring 2014, the Documentation Working Group (DocWG) has taken over the decisions and planning for tools, policies, and procedures for Drupal documentation. The DocWG maintains a section containing the current goals, priorities, and projects of the Documentation Working Group.

Prior content of this page

In December 2010, the incoming and outgoing documentation team leadership got together in Vancouver, B.C., with a few Drupal.org redesign and infrastructure people to make plans and set realistic goals for the next year, in the areas of structure, team building, organization, and processes. The resulting goals are listed here.

Update: March 2011: There is also a new longer-term goal of building a better help system for in-line help in Drupal 8 is being discussed on http://drupal.org/node/1095012 .

Update: October 2011: We have been discussing some new long-term goals on the Documentation team forums on groups.drupal.org. We now also have a "docs infrastructure" issue tag to unify the issues we are working on. The most active/current issues there would be a good place to start to figure out the priorities.

Note: If you're looking for information on our current priorities for documentation that needs to be written, check the Current Documentation Priorities page instead.

Team building and sprints

One of our highest priorities for the Documentation team is to recruit, motivate, and retain a team of contributors to Drupal documentation. 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 people 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 (which you will be able to see in the News archive); other lines of communication include Twitter (@drupaldocs), the Documentation Team group on groups.drupal.org, the #drupal-docs channel on IRC, and the Contribute to Documentation pages on Drupal.org.
• 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. This is in progress.
• 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. These are both part of the Drupal 8 help system proposal.
• 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 "docs infrastructure" 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.