Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Possible/Future Projects of the Documentation Working Group

Last updated on
8 August 2023

This documentation needs work. See "Help improve this page" in the sidebar.

As of July 2014, the Documentation Working Group has adopted a set of Goals and decided on a list of priority Projects for drupal.org documentation-related tools and software.

This page and sub-pages list other ideas that were under consideration, but which did not make our list of priorities in this round.

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

List of ideas for future consideration

Note: In this table, the "goals" are listed on https://www.drupal.org/governance/docwg-goals

Goal(s) Policy or Tool Idea & Issue
Link		 Notes
recruit-find, recruit-learn policy Sprints Docs sprints knock down barriers to contributing, but do not reach many people at a time and things do not really get finished. Can we get other community members to hold mini-sprints? Have a global sprint day?

Focused sprints on specific items are good but big non-focused sprints, not so much.

Encourage people to do personal sprints to update sections of the docs. How to plan a docs sprint: https://drupal.org/node/424194

Maybe working with others on docs is not as useful as it is with coding?

Current action: Make sure all sprints we know about are listed in our This Month in Drupal Documentation posts.

Possible future action: Organize sprints. Encourage others to hold sprints.
recruit-learn policy Mentoring program Create a docs mentoring program for contributors

Examples for existing tasks with a template: https://drupal.org/contributor-tasks/writers
recruit-motivate policy Rewards/recognition Figure out how to better recognize and reward documentation contributions

Current action: Recognize people in This Month in Drupal Documentation posts.

Future ideas:

Can we make a “tag cloud” of docs editors?

Can documentation contributions be more visible? (Dries keynotes, module maintainers mentioning docs writers, etc.)?
recruit-motivate tool Widget for linking to pages that need work #946846: Make widget for promoting docs pages that need work This is a widget people can embed in their site to link to a docs page that needs work
use-find, use-understand tool Ability to navigate book outline(s) without page loads:
#1289090: [meta] Improve search/navigation for d.o community docs
#1508832: Support +/- expand/contract in Book navigation on Drupal.org		 Need some way to go up/down/through book outlines without having to load a page each time you go down a level.

This may be fixed as part of our "multiple outlines" priority. See https://www.drupal.org/governance/docwg-goals
manage-write, manage-organize tool Easier way to arrange outlines
#2128143: proposal: allow documentation editors to order child pages of a book page		 Currently, to change a book outline order, you have to edit the weight of each individual page. Very tedious.

Would like to see a tool showing a limited amount of hierarchy (full hierarchy is too big!) within a book, with drag-and-drop ability.

This may be fixed as part of our "multiple outlines" priority. See https://www.drupal.org/governance/docwg-goals
use-find, use-related tool Documentation index
comment #18 on #1278256-18: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained.		 Develop a (possibly hierarchical) index taxonomy for the Community Documentation.
Put pages into this index.
On a node, show which index(es) it is listed in, ideally as a link to that letter in the index so you can find related index topics

Conclusion: Hard to enforce consistency. So, stick with the Keywords we have now and don’t need anything else for the moment.
use-find, use-understand tool List tables of contents on Community Documentation landing page
Listed on omnibus issue #1287784: Follow-ups to improve the community docs		 Have a collapsed listing of the TOC from each Book along with the list of books on drupal.org/documentation landing page

Conclusion: Not a bad idea but low priority. Just saves people one click from the landing page. Would need to make sure that the highest level of the books is a useful TOC (some are OK, some are not).
use-version, use-dups, manage-write tool Conditional Text
#995362: Conditional Text ability needed for book pages		 Pages would be able to have information for multiple versions of Drupal or modules, while showing only one at a time (using fieldsets or show-hide sections) -- more compact than just including multiple versions in the text of the page.

Allows one page to cover several versions of Drupal, when processes and most of the text is the same, but only a few things are different

Ideally, would like to be able to have a way at the top of the page to say something like “Show D7 version” or “Show Views 7.x-3.x version”, and open/close all the text boxes in the whole page.

Conclusion: Seems like a “nice to have”. Should improve the experience of documentation readers. not highest priority right now
use-find, use-understand, use-dups tool Ability to have “versioned” pages Have Drupal 6, Drupal 7, Views 6.x-1.x, Views 6.x-2.x etc. versions of the same page

Display in tabs or links so you can switch easily between them

Only show one version in the Outline

Alternative to "Conditional Text" idea (all info in same node vs. set of related nodes). Disadvantage here: lots of pages with very similar content, hard to maintain

Conclusion: Seems to be difficult to implement, far from what we have now. Prefer Conditional Text idea for now.
manage-write, find-related tool Related Links field Separate field for links to related (off-site) tools, videos, etc.

Note: There is always the danger that off-site links get stale... makes docs hard to manage? This came up on the video embedding discussion on https://drupal.org/node/1246118 and is also why we host all images embedded into pages locally now.

Conclusion: Separate field not too useful. Just put it in the text near where it’s related.
manage-write tool Spell checker Most browsers have this now. Not really needed these days.
manage-write tool Edit by section Ability to edit part of a page in-place instead of the entire page (many Wikis have this ability)

Conclusion: We don’t need this. Should split up pages if they are long enough that you don’t want to edit the whole page.
manage-find, use-understand policy Page taxonomy updates Page Status: add “Stub” option

Documentation Type: Tutorial, Reference

Conclusion: We have “incomplete” (probably too close to ‘stub’). Don’t really need a documentation type taxonomy (people don’t often set up the existing taxonomies anyway, and not super useful.)
use-find tool Relate Forum topics to Docs pages Ability to link a Forum topic to a Docs page with a noderef field.
On Docs page, list related forum discussions
manage-find tool Thumbs-up/down ratings for comments Users can give comments thumbs up/down

Docs editors can locate comments with lots of thumbs up/down for inclusion into page or deletion as appropriate

Conclusion: Probably more useful for forums. This is only useful if we plan to keep comments on docs pages, and we plan to use issues instead. See https://www.drupal.org/governance/docwg-goals
manage-find tool Ability to flag a forum comment as a “Solution” Docs editors could then locate these “solutions” and make docs pages out of them

Could sort forum comments with “solutions” at top (like StackOverlow?) or highlight the “solutions”
manage-find tool Comment management view
#1470962: Documentation comments management view page		 If we are keeping comments, it would be useful to have a view for managing them

This is only useful if we plan to keep comments on docs pages, and we plan to use issues instead. See https://www.drupal.org/governance/docwg-goals
manage-find tool Analysis of search terms Tool to view drupal.org search terms to figure out what documentation people are searching for or what topics are most important
manage-find tool Analysis of page popularity
#780982: Popular docs pages list		 We should have this information in Google Analytics
manage-write tool Off-line docs editor
#996040: Offline text editor for Drupal docs		 Conclusion: Why would we need to provide one if it is off-line?
use-learn policy Build tutorials Depends on the “multiple outline” tool, which is one of our current priorities. See https://www.drupal.org/governance/docwg-goals

Make some outlines of a “tutorial” nature, that will let people with little knowledge in an area learn what they need to know, step-by-step, making sure background info is provided

These would provide “road maps” so people know what is important to learn when they don’t have the background (as opposed to “I need to solve this particular problem”)

May involve writing some new pages, if needed pages do not exist, or splitting larger pages into smaller chunks for better reusability.

May need to do some usability/focus groups to decide what tutorials we need... or look at the curriculum of existing training that’s out there?

Consider the “Audiences” for documentation, and make tutorials for each
Start with prioritizing beginner tutorials.
use-find tool Advanced Search Filtering down keywords searches of documentation by:
- What book it’s in
- What project it’s related to (requires “projects related to pages” tool)
- Version
manage-write, use-related tool Keyword glossary: see comment #7 on #1287784-7: Follow-ups to improve the community docs Develop a keyword glossary (or use the one we already have at glossary).

Make an easy way to link keywords in doc page text to the glossary, so they do not need to be redefined everywhere.
use-read tool Collapsible sections
#1921962: Add ability to collapse sections below headings		 Make it so you can collapse sections on Docs pages (using headers to define “sections”)
use-read tool Display term descriptions
#313439: Add description to Page Status taxonomy terms displayed on book pages		 This is primarily for the Status taxonomy on Docs pages. The idea is to make it clearer what the different status terms mean. We would need to add the descriptions to the terms themselves (fill in the Description fields that already exist), and then use a few lines of code to display them.
use-read tool Display comments in a separate page
#1402848: Put documentation comments in a separate tab		 If we are keeping comments around, we might want to put the discussions in a separate page from the docs themselves.

This is only useful if we plan to keep comments on docs pages, and we plan to use issues instead. See https://www.drupal.org/governance/docwg-goals
use-find tool Add Drupal version(s) to page title
#1413004: Add Drupal versions to page title for more clarity and better SEO		 Idea would be displaying automatically from the taxonomy, if present.

Would improve SEO and usability of Google searches.

If displayed in d.o search results, would also improve there. Users could see at a glance which version of a page to get.
recruit-motivate tool Recognize contributors to documentation for a project For recognition, list in Profile projects whose documentation you have contributed to, and on Project page, list people who contributed to docs.

Depends on adopted idea: project field for documentation. See https://www.drupal.org/governance/docwg-goals

Help improve this page

Page status: Needs work

You can: