Problem/Motivation

#3041924: [META] Convert hook_help() module overview text to topics for the workspaces module.

Proposed resolution

Take the information that is currently in the hook_help module overview section for this module, and make sure the information is in one or more Twig help files. Steps:

  1. Find the hook_help() implementation function in the workspaces.module file. For example, for the core Contact module, the module files is core/modules/contact/contact.module, and the function is called contact_help().
  2. Locate the module overview portion of this function. This is located just after some lines that look something like this:
      switch ($route_name) {
        case 'help.page.contact':
    

    And ends either at the end of the function, or where you find another case 'something': line.

  3. We want to end up with one or more topics about the tasks that you can do with this module. So, read the help and figure out a good way to logically divide it up into tasks. Each task will need to be in its own topic.
  4. See if some of these tasks are already documented in existing topics. Existing topics could be in one of the following directories:
    core/modules/help_topics/help_topics
    core/modules/workspaces/help_topics
    core/help_topics
    

    Note that to see existing topics, if the patch for #2920309: Add experimental module for Help Topics is not in your testing environment yet (because it has not yet been committed or was committed after you did your git pull or git clone command), you will also need to apply that patch.

  5. For each task that needs to be written up, either add it to an existing topic, or create a new Twig topic file (see examples in the above locations). New Twig templates should be created in this module's help_topics directory, or in the core area if the information spans several modules or if the information should be visible before the module is installed. For instance, it might be useful to know that to get a certain functionality, you need to turn on a certain module (so that would be in Core), but then the details of how to use it should only be visible once that module is turned on (so that would be in the module).
  6. For new topics, file names must be workspaces.TOPICNAME.html.twig -- for example, in the Action module, you could create a topic about managing actions with filename action.managing.html.twig . Also, attached to the parent issue there is a sample help topic Twig file that you can use as a template when making your patch (you will need to change the file name and extension and save it in the correct directory).
  7. Do not just copy the text of the old module overview word-for-word. We don't want an overview of the module -- we want one or more topics that are task-centered, that would be useful for someone managing or building a Drupal site. If you need to explain a concept, put that in a separate section or sections within the related task topic, with headers like "What is/are...?" question, such as "What are actions?".
  8. Add metadata to the top of the Twig topic (see examples) -- it will need to either be a top-level topic, or marked as "related" to an existing topic.
  9. Make a patch file that adds/updates the Twig templates in Core. The patch should not remove the text from the hook_help() implementation (that will be done separately).

Remaining tasks

a) Make a patch (see Proposed Resolution section).
b) Review the patch:

  1. Apply the patch. (If the patch for #2920309: Add experimental module for Help Topics is not in your testing environment yet, you will also need to apply that patch).
  2. Turn on the experimental Help Topics module in your site.
  3. Review each topic that is created or modified in this patch. Make sure the text is clear and does not contain grammar/punctuation errors, and that the links within the text work and the instructions for tasks work. The topics are files in the patch ending in .html.twig. If you find a file, such as core/modules/action/help_topics/action.configuring.html.twig, you can view the topic at the URL admin/help/topic/action.configuring within your site.
  4. Also verify that it is task-based help, and that concepts that need to be explained are in separate sections with "What is/are" questions as headers (such as "What is an action?").
  5. Read the old "module overview" topic for the module, at admin/help/MODULENAME. Verify that all the tasks described in that overview are covered in the topics you reviewed.

User interface changes

Help topics will be added to cover tasks currently covered in modules' hook_help() implementations.

API changes

None.

Data model changes

None.

Release notes snippet

None.

Comments

shwetaneelsharma created an issue. See original summary.

jhodgdon’s picture

Status: Postponed » Active

Parent issue was committed, so we can un-postpone this now!

jhodgdon’s picture

Status: Active » Closed (duplicate)
Related issues: +#3047722: Convert content_moderation, workflows module hook_help() to topic(s)

This is getting combined with another issue.