|Issue tags:||docs infrastructure|
We need a better in-line Help system in Drupal. Currently, we have hook_help(), which has many problems:
- In code, so not editable by docs people (mostly)
- No navigation or searching
- Not flexible enough, really only good for the main module help page and some contextual help, so some contrib modules use other systems (such as the Advanced Help module).
- Not easy to add site-specific help
- Can't really view it outside of a Drupal site, so we've duplicated it in the drupal.org help
- Not cross-linked
The proposed system is described in full on this page:
The main components are:
- Help topic entities (fields and topic types)
- Conditional text (one topic can cover various audiences and various Drupal/module versions)
- Linking (topic to topic, Drupal page or field on page to topic, bi-directional)
- Navigation and searching, including a glossary
- Client/server to import official help topics into your site
- Flexible outlines (can build outlines specific to your Drupal site)
Here is a list of the tasks that need to be done to accomplish the goals/specs outlined on
- Conditional text - define conditional text plugin structure and have an input filter for displaying conditional text. This was created as a 2011 Google Summer of Code project by Yorirou, and is now the Conditional Text project. We probably need a few additional features added to it (see conditional text issue queue).
- Help - would define the Help Topic entity, the Map entity, the topic types and their fields. It would also handle the contextual links. It would associate the module overview topics with the module (like the existing hook_help system). And it would have options for display, such as hiding topics by the Permission field vs. showing all topics. Status: Carolyn is working on this in sandbox: http://drupal.org/sandbox/carolyn/1342818
- Map/Outline Builder - user interface for building Maps. There are several options here. One is being worked on and discussed by Itangalo and others on #995370: Want the ability to create multiple outlines/maps, and there is also a related issue at #5901: Let a book page appear in multiple books. Several other people have working prototypes of this too. We probably just need to pick one and make sure it has the features we need, and is as simple as possible.
- Glossary - would build the A-Z glossary and have a text filter for pop-up glossary links. [Status: Need someone to work on this!]
- Updater Client and Server - Server would live on help.d.o (not a core module probably) and export the help docs. Client would be a core module and would let a site builder pull in docs and be notified when new docs are available. [Status: People have expressed interest in working on this, but I haven't received any updates.]
- Workflow - For the help.d.o site itself, we would need an editorial workflow module, which we would hopefully be able to accomplish with the Workbench and or Revisioning modules (with some custom components probably?). For instance, we probably want to allow people to freely edit topics, but we probably don't want their revision to become the main published revision until it's been reviewed (we need to be careful, because at least some of the topics will need to be translated) (probably all?). We might not want people to freely create topics, because we want to keep the size of the site under control. This is being worked on: issue - #1283496: Help/Docs system: editorial/translation workflow and permissions
User interface changes
- New UIs for building outlines, writing help topics (essentially like node/add), defining conditional text filters, help navigation/searching, and importing help topics from server(s)
- Remove existing help user interface (such as it was)
- No more hook_help()
- New API for putting contextual help links on Drupal pages
Original report by jhodgdon
This issue is to start a discussion on how the in-line help system could be improved for Drupal 8, independent of what was discussed for Drupal 7, as a replacement for the current help.module system.
Just to be clear, there are several types of "help" that we can enumerate:
1) Contextual information and UI text, such as field labels and descriptions. This type of information is probably out of scope for this issue.
2) Longer pieces of contextual information, such as overall help text for a page, extra help beyond field descriptions, expanded information on input formats, etc. This type of information should have some kind of show/hide functionality or it could pop up when you click on a ? near a field. This type of information is probably within the scope of this issue.
3) Long, detailed background information and how-to information. Some of this may belong on drupal.org rather than inside the project, or it could conceivably be in both places (if d.o or a separate help.d.o had a way to display this information from projects). Ideally, this information would have navigation features (search/sort/hierarchy?) and linking (cross-linking between documentation items, and linking between site pages/form fields/page elements and help items). This type of information is definitely within the scope of this issue.
The system that is designed (besides features stated above) would need to satisfy these requirements:
a) Allows non-programmers to edit the in-line documentation for Drupal (core/contrib) and contribute it back to the project.
b) All help text needs to be translatable.
c) Help text should to be able to contain HTML-type formatting.
d) Whether we want PHP logic included in help is open to question. Some of the hook_help() implementations in Drupal Core currently use PHP to do things, such as to generate a list of links to your installed Fields and their help pages.
Let the discussion begin...