Problem/Motivation

#3041924: [META] Convert hook_help() module overview text to topics for the datetime, datetime_range, field, field_ui, link, options, telephone, text modules.

Proposed resolution

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

  1. Find the hook_help() implementation function in the core/modules/MODULENAME/MODULENAME.module file(s). 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, and possibly a section header topic. So, read the help and figure out a good way to logically divide it up into tasks and sections. See Standards for Help Topics for information on how to do this.
  4. See if some of these tasks are already documented in existing topics. Currently, all topics are in core/modules/help_topics/help_topics. Note that to see existing topics, you will need to enable the experimental Help Topics module (available in the latest dev versions of Drupal 8.x).
  5. For each task or section topic that needs to be written, make a new Twig topic file (see Standards for Help Topics) in core/modules/help_topics/help_topics. You will need to choose the appropriate module prefix for the file name -- the module that is required for the functionality. Alternatively, if the information spans several modules or if the information should be visible before the module is installed, you can use the "core" file name prefix. 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 the core prefix), 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 prefix).
  6. File names must be MODULENAME.TOPICNAME.html.twig -- for example, in the Action module, you could create a topic about managing actions with filename action.managing.html.twig (and "MODULENAME" can be "core" as discussed above).
  7. Make a patch file that adds/updates the Twig templates. 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.
  2. Turn on the experimental Help Topics module in your site, as well as the module(s) listed in this issue.
  3. Visit the page for each topic that is created or modified in this patch. The topics are files in the patch ending in .html.twig. If you find a file, such as core/modules/help_topics/help_topics/action.configuring.html.twig, you can view the topic at the URL admin/help/topic/action.configuring within your site.
  4. Review the topic text that you can see on the page, making sure of the following aspects:
    • The text is written in clear, simple, straightforward language
    • No grammar/punctuation errors
    • Valid HTML -- you can use http://validator.w3.org/ to check
    • Links within the text work
    • Instructions for tasks work
    • Adheres to Standards for Help Topics [for some aspects, you will need to look at the Twig file rather than the topic page].
  5. Read the old "module overview" topic(s) for the module(s), at admin/help/MODULENAME. Verify that all the tasks described in these overview pages 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

dwebpoint created an issue. See original summary.

dwebpoint’s picture

Status: Active » Needs work
jhodgdon’s picture

Title: Convert datetime, datetime_range, entity_reference, field, field_ui, link, options, telephone, text modules hook_help() to topic(s) » Convert datetime, datetime_range, field, field_ui, link, options, telephone, text modules hook_help() to topic(s)
Issue summary: View changes

Just a note that the entity_reference module is hidden, so we shouldn't be making topics for it specifically. Entity Reference fields are provided by Drupal Core outside of the module space, so we probably need a topic on them (or part of a topic) as part of this issue, but if so it should go in the "core" namespace for topics not "entity_reference".

jhodgdon’s picture

Assigned: Unassigned » jhodgdon
Status: Needs work » Active

I'm going to work on a patch for this issue (also it never had a patch, so setting status correctly).

jhodgdon’s picture

StatusFileSize
new8.7 KB

Here's a start.... I've made an overview topic, and content-empty files for the other topics that I think we need for this section of help. I'll work on it some more in the next day or two, to fill in the content. If other topics get committed in the meantime, we can add more cross-links too.

jhodgdon’s picture

Status: Active » Needs review
StatusFileSize
new12.06 KB
new18.3 KB

Here is a patch with all the topics filled in this time.

Status: Needs review » Needs work

The last submitted patch, 7: 3087562-7.patch, failed testing. View results

jhodgdon’s picture

Doh! I forgot to apply the patch and test before I uploaded. Whoops. I'll fix it tomorrow.

jhodgdon’s picture

Status: Needs work » Needs review
StatusFileSize
new15.92 KB
new18.56 KB

Here's a much better patch, which I actually tested (and looked over the topics) this time.

Status: Needs review » Needs work

The last submitted patch, 10: 3087562-10.patch, failed testing. View results

jhodgdon’s picture

Status: Needs work » Needs review
StatusFileSize
new18.56 KB

Fixed bug in patch. Wrong related topic ID in one place (field_ui.form_display should have been field_ui.manage_form).

amber himes matz’s picture

Status: Needs review » Reviewed & tested by the community

This patch is to add help topics around core-provided content entities, entity sub-types, field types and how to manage their fields, display, forms, formatters, and widgets. Appropriate overview topics were written as well as topics that provide step-by-step instructions on how to do certain tasks.

The added and modified topics in this patch include describing functionality provided the modules mentioned in the title (datetime, datetime_range, field, field_ui, link, options, telephone, text) but more importantly provide more generalized that instructions that can be applied to any entity type when managing fields or display.

In addition, the topic on accessibility overview was added to the relevant topics as a related topic as it provides instructions for how to change the drag-and-drop interface into a more accessible interface by displaying row weights. (For example, the manage display form.)

Finally, existing topics on blocks were updated to add new related topics added in this patch.

Note: the "Managing content structure" overview topic is in the "core" topic namespace so that it will always display top level. And isn't dependent on another module to be enabled.

I've reviewed the patch and it looks both technically correct to me and a very helpful set information for Drupal site administrators. Thanks @jhodgdon for writing this up.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 12: 3087562-12.patch, failed testing. View results

jhodgdon’s picture

Status: Needs work » Reviewed & tested by the community

Known unrelated test fail

jhodgdon’s picture

Issue tags: +blocker

This topic is blocking progress on other topics... Any chance we could get it committed sometime soon?

alexpott’s picture

Status: Reviewed & tested by the community » Fixed

This looks great. I'm sure there are improvements that can be made but nothing jumps out as incorrect and improving this will be easier once it is in core.

Committed and pushed 954c622b45 to 9.1.x and 8a947dd2b3 to 9.0.x and ea742ff025 to 8.9.x. Thanks!

  • alexpott committed 954c622 on 9.1.x
    Issue #3087562 by jhodgdon, Amber Himes Matz: Convert datetime,...

  • alexpott committed 8a947dd on 9.0.x
    Issue #3087562 by jhodgdon, Amber Himes Matz: Convert datetime,...

  • alexpott committed ea742ff on 8.9.x
    Issue #3087562 by jhodgdon, Amber Himes Matz: Convert datetime,...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.