Assuming that #2351991: Add a config entity for a configurable, topic-based help system gets into Drupal Core, we'll want to convert some of the existing information that is hidden within existing module overview help pages to be Topics. This issue is for tracking that. Currently postponed until #2351991: Add a config entity for a configurable, topic-based help system is finished.

Notes on what topics to create (possibly):

  • The parts of hook_help() that deal with providing page-specific help need to stay in hook_help(). This is only for the module overview pieces -- and we still want to have module overview topics that describe what each module does. So what we're aiming for is to pull out task-oriented or background-knowledge-oriented information into modular topics that can be arranged in a user-understandable hierarchy.
  • If the main module topic is doing something dynamic, that will also need to stay in hook_help(). Only static HTML can be converted to the new system, not PHP code.
  • We could have a "Glossary" topic, with proposed machine name core_glossary. Then there could be individual topics with titles like "Glossary: Entity" -- each one would NOT have "Top level" checked, would put _core_glossary in its "list on" field, and would have machine name "glossary_specific_word". In this way, modules and themes and etc. could provide their own glossary terms, and they would be automatically listed on the Glossary page.
  • We could also have a "Field list" topic, machine name core_fields, and individual field topics like "Field: Telephone" (machine name field_telephone, not top level, marked as "list on core_fields"). Would work like Glossary. The glossary_field topic would list this as "Related", and vice versa. The Field module topic would also list this as Related.
  • Creating content types with fields [maybe have a group of topics about entities and fields]
  • User interface basics - would cover things like using the drag-and-drop interface and the show row weights feature seen on many pages. Screen shots might be helpful for this!
  • Accessibility features - maybe make this part of user interface basics?

Notes on mechanics:

  • To find existing help to be converted, go to admin/help and read the module overview topics.
  • To edit a new help topic on your site, go to admin/config/development/help and click "Add new topic". [TBD: this URL may change], and enter the information, and save. After saving, go to admin/help and verify the topic is there. Click through and make sure it looks OK. Edit until it does.
  • To get this topic into Core, use the config export page to export the config for this new topic. Save the file with a file name like "help.topic.foo_bar_baz.yml" and put it into the core/modules/foo_bar/config/install directory. Then make a patch to add this file to Core.
  • Notes about editing topics:
    • For links internal to the site in the text, such as to admin pages, you'll need to find the route name [TBD: provide information on how to do that] and use something like <a href="[route:the_route_name_here]"....
    • [TBD show how to make inter-topic links in the text]
    • If you make a topic out of something that was in a module overview, if appropriate, you may want to also delete it from the module overview hook_help() and replace it with a link to that topic [TBD: write up instructions for how to do this].
    • The Configurable Help entity comes with two "Help" text formats. Use those when you create these help topics, and don't use Full HTML and other text formats that come from the Standard install profile or that you created on your own site (those are not guaranteed to be present on every site).
    • Related topic links: If module A depends on module B and you think topics related to A should be listed as related on B's topic pages, then when you are creating help topics for A, list B's topics in the "List on" section. If you think B's topics should be shown on A's topic pages, then when you are creating A's topics, list B's topics directly in the Related section. In this way, only topics that depend on A and A's actual dependencies should be listed as Related on module A, but when B gets turned on, its topics will also be listed on A's topic pages. However, sometimes there will be cases where A and B are related but neither one depends on the other... in this case it is OK to list it on either one, whichever makes the most sense.
    • If we have a mechanism for including images, and you do so in a topic, you may want to make sure they are just generic icons or something that is independent of language so that we don't have to create 160 different versions of the image and ship them with Drupal Core.

Comments

jhodgdon’s picture

Issue summary: View changes

Added additional notes.

jhodgdon’s picture

I had a couple of thoughts about how to structure some help topics:

a) We could have a "Glossary" topic, with proposed machine name core_glossary. Then there could be individual topics with titles like "Glossary: Entity" -- each one would NOT have "Top level" checked, would put _core_glossary in its "list on" field, and would have machine name "glossary_specific_word". In this way, modules and themes and etc. could provide their own glossary terms, and they would be automatically listed on the Glossary page.

b) We could also have a "Field list" topic, machine name core_fields, and individual field topics like "Field: Telephone" (machine name field_telephone, not top level, marked as "list on core_fields"). Would work like Glossary. The glossary_field topic would list this as "Related", and vice versa. The Field module topic would also list this as Related. This would solve #2332687: Lost help for field types from Core/Field.

jhodgdon’s picture

Issue summary: View changes

Updating the issue summary. The new plan, assuming the parent issue gets done, is not to get rid of any existing hook_help() module overview topics, but to edit them down to being just module overviews, and provide information that is more user-orieinted in these help topics.

jhodgdon’s picture

Issue summary: View changes

I've been working on this configurable help module in a sandbox, and over there I had a related issue: #2658680: Make some topics / redirect purpose of topics slightly. I had some topic ideas there for core topics, and am adding them to this issue's summary now.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

jhodgdon’s picture

Status: Postponed » Closed (won't fix)

Parent issue is closed / won't fix. This one should be too.