Documentation Working Group Goals, Priorities, and Projects

Part of the mission of the Documentation Working Group (DocWG) is to ensure that the Drupal project has excellent tools and procedures in place for documentation. This page and section contain information on the goals, priorities, and projects of the DocWG (tools and procedures we are working on improving), as well as an archive of past documentation tools/procedures initiatives.

If you have questions or comments about our goals, priorities, or projects, contact the DocWG.

Current Goals

The DocWG has adopted the following goals, each of which has a "code name":

Recruit

Restructure the “Documentation Team” so people feel more empowered to edit and write Community Documentation pages. Components:

1. (recruit-find) Find new people to contribute to documentation
2. (recruit-motivate) Motivate people to contribute and continue contributing
3. (recruit-learn) Make sure new contributors learn how to contribute (mentoring, on-ramp tasks, etc.)

Manage

Add tools that empower individuals and groups to manage, write, and edit sections and pages of the documentation, and potential contributors to find pages to work on of interest. Components:

1. (manage-find) Find a page that you want to edit
2. (manage-add) Find a place to add new information
3. (manage-track) Keep track of and review documentation updates
4. (manage-organize) Organize documentation
5. (manage-write) Author/edit documentation efficiently

Translate

Add tools that empower foreign-language communities to translate documentation (on their sites)

Use

Improve the experience of users of the Drupal Documentation. Components:

1. (use-relocate) Find documentation again that you have seen before
2. (use-find) Locate information on a specific topic efficiently
3. (use-learn) Improve knowledge when you don’t even know what you should be learning about (guided tutorials)
4. (use-understand) Understand the conceptual documentation landscape, documentation status, documentation organization, where you are in the navigation, etc.
5. (use-related) Find information related to the page you are on
6. (use-version) Find information related to the correct version of Drupal/modules
7. (use-dups) Avoid having many pages with the same or similar information in the docs pages, which leads to user confusion
8. (use-read) Make sure documentation pages are easy to scan, read, and understand

Priorities and Projects

The Docs WG has been meeting for several months to decide on our priorities and projects, in the area of Documentation tools and infrastructure. As of July 2014, here is a list of what we are hoping to accomplish in this area, depending on funding and/or volunteer resources. If you'd like to help out on one of these projects, contact the DocWG or add a note to the linked issue (if there is one).

As projects in this list are completed, they'll be moved to the child page "Past and Completed Projects", or sub-pages.

2014 Projects

Locked pages explanation

We have some pages that are “locked”. We have an explanation at https://www.drupal.org/node/319685 but the “locked” pages themselves do not indicate what is going on. We need to add a short explanation to these pages. Issue: #1744878: Add a small note how to change a page on the pages that cannot be edited by regular people

Goals: manage-write

2015 Projects

Ability to "follow" documentation pages and learn about substantive changes to them

This involves a few components:

(a) Ability to flag a documentation page as "followed".

(b) Ability when editing a documentation page, to mark a revision as "substantive", as opposed to "minor" (like typographical error fixes).

(c) When you are looking at the revision log, some indication of whether each revision involves a substantive or minor edit (or the ability to filter out minor edits).

(d) Ability for users to set up notifications for "followed" pages, and receive email when these pages have substantive revisions.

(e) Ability for users to see a list of pages they have "followed", and when they were last updated (preferably showing or filterable by "substantive" vs. "minor" edits).

(f) On page https://drupal.org/documentation/manage (which is a view), ability to filter to only show pages with recent substantive revisions (filter out minor revisions).

(g) Nice to have: If you are following a page, you could also choose to be notified when any child page is added or substantively edited.

Issue: #2218551: A user should be able to "follow" a Section of content

Goals: manage-track, translate, use-relocate

Priority: Highest

Link issues to individual documentation pages

We need a way to link issues in the Documentation project (or in individual Contrib projects) to documentation pages on drupal.org. Components:

(a) Node reference field on Issues for "Related documentation pages", displayed on the issue page.

(b) If you are viewing a Documentation page, the related issues would be shown (probably in the sidebar, and we would need to decide whether to show all, just open issues, go to a search, have it hidden in a fieldset, etc.).

(c) If you are viewing a Documentation page, there would be a "Report a problem with this page" link, which would prefill this field and set up an issue in the Documentation issue queue.

Issue: #995292: Noderef field on issues for Documentation project

Goals: manage-find, manage-track, use-understand

Priority: Higher

Maintainership for Documentation pages and sections

We would like to introduce the concept of Community Documentation pages (and sections, which would include child pages, grandchild, etc.) on Drupal.org having "maintainers". To implement:

(a) Documentation pages would need a button that would say something like "Sign up to maintain this page", and a section in the sidebar listing all the people (link to d.o profile) who have signed up as maintainers.

(b) This should also trigger notifications when pages in the section are updated substantively.

(c) Maintainers need a dashboard page where they can see pages they maintain and when they have last been updated and by whom. It would be great if this was also visible on their user profile, similar to projects they maintain.

(d) In the Maintainers area on the docs page sidebar, we need to make clear that everyone is still encouraged to edit pages -- the maintainers are just overseeing the edits (short description with link to a longer page explaining what the responsibilities are).

Goals: recruit-motivate, manage-track, use-understand, use-read (this last assumes that "maintained" pages end up having better writing/information on them)

Priority: Higher

Issue: #2332855: Maintainership for Documentation pages and sections

Ability to put one Community Documentation page into multiple outlines

Currently, the Community Documentation uses the core Book module, which allows each page to be part of exactly one Book. This leads to (a) confusion about where to put documentation that logically belongs in more than one place, and/or (b) duplicated documentation. It would be much better if one page could be instead included in multiple "books" or "outlines" or "maps", whatever you want to call them.

As a corollary, a better way to create and modify outlines will be needed [drag-and-drop with an auto-complete to add new pages to an outline].

And one other feature: If we allow pages to appear in more than one outline, then we would need to replace the Book Navigation we currently have on the sidebar with a different block, which would hopefully show all the outlines the book is part of, and allow you to navigate any of them. So, they might need to be mostly hidden (except titles) with open/close links to expand each one out.

Issue: #995370: Want the ability to create multiple outlines/maps

Goals: manage-organize, manage-write, use-find, use-learn, use-related, use-dups

Priority: Higher

Relate Community Documentation pages to the Projects they are documenting

We need an explicit way to link a module's documentation to its related project page. In the module project page we already have a field to link to the documentation. But if you go to the documentation you won't see a link to the project page unless someone has manually created a link within the text. The link between documentation and project is a critical bit of data that should be in a separate field. (This should not apply to Drupal Core, but only to other projects -- by definition, all docs on drupal.org presumably relate to Drupal Core). The easiest way to do this is probably a node reference field on Documentation pages where you could enter one or more related projects (excluding Drupal Core hopefully).

As a secondary task, it would probably be good if a tab on the Project page automatically listed all documentation that was linked, while making clear that these are Community Documentation pages and not necessarily the "official" documentation. Maybe the project's main Documentation link (which the project maintainer can designate when editing the project) was also shown at the top of this page?

Issue: #733908: Add noderef field for project to doc pages, and see also #1543262: Improve the integration between a project and its related documentation

Goals: use-find, use-related

Priority: High

Add a real WYSIWYG editor for documentation pages

The BUEditor that we currently have on Drupal.org is not a WYSIWYG editor. Drupal 8 Core has CKEditor, which is accessible and usable. We should be able to have it in Drupal 7 as well, for editing documentation pages. It should be turned off by default, though, so as not to affect people who really don't want it.

Goals: manage-write

Priority: high