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:
- 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().
- 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.
- 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.
- 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).
- 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).
- 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).
- 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:
- Apply the patch.
- Turn on the experimental Help Topics module in your site, as well as the module(s) listed in this issue.
- 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.
- 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].
- 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
Comment #2
dwebpoint commentedComment #3
jhodgdonComment #4
jhodgdonJust 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".
Comment #5
jhodgdonI'm going to work on a patch for this issue (also it never had a patch, so setting status correctly).
Comment #6
jhodgdonHere'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.
Comment #7
jhodgdonHere is a patch with all the topics filled in this time.
Comment #9
jhodgdonDoh! I forgot to apply the patch and test before I uploaded. Whoops. I'll fix it tomorrow.
Comment #10
jhodgdonHere's a much better patch, which I actually tested (and looked over the topics) this time.
Comment #12
jhodgdonFixed bug in patch. Wrong related topic ID in one place (field_ui.form_display should have been field_ui.manage_form).
Comment #13
amber himes matzThis 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.
Comment #15
jhodgdonKnown unrelated test fail
Comment #16
jhodgdonThis topic is blocking progress on other topics... Any chance we could get it committed sometime soon?
Comment #17
alexpottThis 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!