Problem/Motivation

#3041924: [META] Convert hook_help() module overview text to topics for the history, statistics, tracker module(s).

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.

CommentFileSizeAuthor
#34 interdiff.txt1.62 KBjhodgdon
#34 3055317-34.patch6.37 KBjhodgdon
#29 3055317-29.patch6.38 KBjhodgdon
#29 interdiff.txt1.67 KBjhodgdon
#28 3055317-28.patch6.33 KBjhodgdon
#28 interdiff.txt9.31 KBjhodgdon
#25 3055317-25.patch4.75 KBjhodgdon
#17 Screen Shot 2019-07-30 at 2.16.39 PM.png85.99 KBalonaoneill
#16 Screen Shot 2019-07-30 at 12.03.51 PM.png5.69 KBalonaoneill
#16 Screen Shot 2019-07-30 at 11.56.01 AM.png65.1 KBalonaoneill
#16 Screen Shot 2019-07-30 at 11.53.33 AM.png42 KBalonaoneill
#13 help-topic-history-statistics-tracker-3055317-13.patch4.89 KBbatigolix
#11 help-topic-history-statistics-tracker-3055317-11.patch1.3 KBbatigolix
#7 3055317-7.patch1.16 KBandypost
#7 interdiff.txt621 bytesandypost
#7 history_after.png19.49 KBandypost
#7 history_before.png15.34 KBandypost
#6 3055317-6.patch1.15 KBandypost
#6 interdiff.txt605 bytesandypost
#3 convert-history-module-hook-help-to-topics-3055317-3.patch1.15 KBamarphule
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

amarphule created an issue. See original summary.

amarphule’s picture

amarphule CreditAttribution: amarphule at DevsAdda for DevsAdda commented
Issue summary: View changes
amarphule’s picture

amarphule CreditAttribution: amarphule at DevsAdda for DevsAdda commented
Assigned: amarphule » Unassigned
Status: Postponed » Needs review
FileSize
convert-history-module-hook-help-to-topics-3055317-3.patch1.15 KB

Created patch for History module, Converted hook_help() to topics.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Postponed

We need to postpone this until the #2920309: Add experimental module for Help Topics gets committed. No idea when/if that might happen right now...

andypost’s picture

andypost
he/him
Primary language Russian
CreditAttribution: andypost as a volunteer and at Skilld commented
Status: Postponed » Needs review
andypost’s picture

andypost
he/him
Primary language Russian
CreditAttribution: andypost as a volunteer and at Skilld commented
Issue tags: +Needs tests
FileSize
interdiff.txt605 bytes
3055317-6.patch1.15 KB

Drupal\Component\Discovery\DiscoveryException: /var/www/html/web/core/modules/history/help_topics/history.overview.html.twig contains invalid meta tag with name='lable' in Drupal\help_topics\HelpTopicDiscovery->findAll() (line 134 of /var/www/html/web/core/modules/help_topics/src/HelpTopicDiscovery.php).
when applied patch

Surely it needs kinda test to make sure discovery returns and able to parse all files from core modules

andypost’s picture

andypost
he/him
Primary language Russian
CreditAttribution: andypost as a volunteer and at Skilld commented
FileSize
history_before.png15.34 KB
history_after.png19.49 KB
interdiff.txt621 bytes
3055317-7.patch1.16 KB

Btw I came to idea is that this kind of help should use some grouping as suggested in
"group" - statistics, history, tracker
Also makes sense to add top level "Core modules" (maybe experimental ones should have own section if enabled)

It looks ugly so changed to "History module overview"

before

after

That's why I'm sure it needs wrapper

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Needs work

Thanks for the patch. However, there are a few problems:
- We really don't want the exact content that was in the hook_help.
- We don't want topics called things like "History module overview".
- Please read the issue summary here. It talks about making task-oriented topics instead of copying what is in the current hook_help.
- Eventually we would probably move this topic into being underneath another topic, but for now I think it is fine to make it top-level.
- We probably don't need that link to the online help, since it isn't actually very useful.
- We definitely do not want a link to the old-style help page for the Views module.

So... The topic needs to be rewritten so that it is oriented towards telling someone how to keep track of viewing history. It should probably cover:
- How to turn on that functionality
- Where to go to see the viewing history
- How long history records are kept
- Views integration

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

As a note, we will need to reorganize the topics on #2687107: Reorganize topics into sensible outline, and/or write more topics -- for now I think it is OK to just make most of them top-level.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Title: Convert History module hook_help() to topic(s) » Convert history, statistics, tracker module hook_help() to topic(s)
Issue summary: View changes

Also, adding more modules to this issue.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix as a volunteer commented
Assigned: Unassigned » batigolix
Status: Needs work » Needs review
FileSize
help-topic-history-statistics-tracker-3055317-11.patch1.3 KB

This patch could serve as a starting point and it addresses most of the remarks from #8 but it still only covers the History module. Not the other 2 modules yet.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

This looks like a good start!

So... RIght now this is a topic that is going into the history module area. So it won't be visible unless the History module is enabled. To me, that means don't say anything about enabling the module, because it's already enabled.

Another thought: I'd really rather that all of the h2 headings in these topics either start with "What is/are" or "Verb-ing something". There's a sample topic linked in the issue summary for reference: https://www.drupal.org/files/issues/2019-04-08/sample.html_.twig_.txt

Also, we don't really want to have 50 top-level topics. So... I think that it might make more sense to make a combined top-level topic with the 3 modules that are on this issue, and put it into the core area. So it might be titled something like "Keeping track of page views" or something similar, and have a section like "What can you track?" that could explain the different types of things that can be tracked by the 3 modules, and mention that which module needs to be turned on to enable that type of tracking. They seem related to me, but maybe I'm wrong about that.

Then each module's own topic page can be listed as Related to that parent page (and thus not top-level), and it doesn't need to explain what tracking is or that the module is enabled (maybe say at the top something about "for more information, see..."), and concentrate on the tasks you can do once the module is enabled. They should probably list each other as related too?

So with that in mind, I have a few other questions that I think could be answered in this topic or in the parent topic:
- How/where is History information normally displayed -- do you see it when you are viewing a page? In views? In a block? Can you configure that (on Manage Display? or elsewhere?) -- I really have no idea.
- I think there must be a views field as well as a views filter that displays history information?
- So maybe here the verb headers would be "Gathering history information", "Configuring the display of history information", and "Using history information in views"?
- I kind of got a clue that each person viewing the site would get to see their own History information, but ... wasn't exactly clear who could see whose information, and that the information was different for each person viewing the site. Can an admin see who has viewed which pages, or count how many people have viewed a page, or is that Statistics module?
- By the end I had the idea that there are kind of 3 page statuses: read, new, updated -- but this wasn't clearly stated in one place. That could be useful (maybe in the parent topic?).

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix as a volunteer commented
FileSize
help-topic-history-statistics-tracker-3055317-13.patch4.89 KB

The attached patch deals with the structural issues:
- creates a top level topic
- adds 3 lower level topics with consistent naming
- uses proper Verb-ing something headings
- ignores any module enabling, or even the existence of the 3 modules

Could you review if the structuring into main and sub topics is as expected?

I had a look at your question regarding the content of this topic. I couldn't find the answers yet, except for the Views field. This does indeed exist. It is called 'Has new content' and the description is 'Show a marker if the content is new or updated.'

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix as a volunteer commented
Assigned: batigolix » Unassigned
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

The structure looks good to me! (Didn't review the content.)

The core topic should go into core/help_topics eventually... though I think right now all of the core topics are in the core/modules/help_topics/help_topics directory so that is OK. I guess we have an issue to move them on
#3025577: Move help topics to core or the correct modules

alonaoneill’s picture

alonaoneill CreditAttribution: alonaoneill at Hook 42 commented
Status: Needs review » Needs work
FileSize
Screen Shot 2019-07-30 at 11.53.33 AM.png42 KB
Screen Shot 2019-07-30 at 11.56.01 AM.png65.1 KB
Screen Shot 2019-07-30 at 12.03.51 PM.png5.69 KB

1. Patch applied via STM
2. The experimental Help Topics module was enabled (Added screenshot below).
3. Reviewed the patch for spelling and grammar. The topics are files in the patch ending in .html.twig.
4. Structuring into main and sub topics doesn't work as expected. "Top level" (Tracking the content of your website) topic shows up on Help Topics page. (Screenshot provided) First "low level" (Tracking user content) topic shows up after you open "top level topic" in Related topics, but the rest (Tracking populat content, Tracking changed content) do not appear. (Screenshot provided)

alonaoneill’s picture

alonaoneill CreditAttribution: alonaoneill at Hook 42 commented
Status: Needs work » Needs review
FileSize
Screen Shot 2019-07-30 at 2.16.39 PM.png85.99 KB

Nevermind! Modules should be enabled to appear.
Structuring into main and sub topics work as expected. (Screenshot provided)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Updated issue summary with better instructions/guidelines

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes
Status: Needs review » Needs work

We have new guidelines now for what we are looking for in both "Section" topics and "Task" topics. Please see new issue summary. This patch needs a quick rework to meet the new guidelines. Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

We've migrated the help topic standards to https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... so updating issue summary again.

volkswagenchick’s picture

volkswagenchick
she/her
Primary language English
Location San Francisco Bay Area
CreditAttribution: volkswagenchick at Kanopi Studios commented
Issue tags: +badcamp2019

Tagging this for badcamp2019. (October 2-5)

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

We just found out that all topic Twig files currently need to go into core/modules/help_topics/help_topics (with their finalized module-based file names), for the time being until the Help Topics module is stable. Updating issue summary. Patch will need to be updated too.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs work » Needs review
FileSize
3055317-25.patch4.75 KB

Here's basically a reroll of this patch to conform with two things:
- All files need to go into core/modules/help_topics
- New meta-data format at top of files
I left the file names the same, and everything inside them actually, just moved the files and rewrote the meta-data in the new format.

I attempted an interdiff but it didn't work very well. Anyway it's just the top meta lines that were changed from the last patch, so it's not worth reviewing this patch. I haven't reviewed the content yet. Decided it would be best to do this in 2 passes. Setting this to needs review to launch the test bot and make sure the syntax passes the tests in the meantime; will review the text soon and probably make a new patch as my review if I find a few things to update.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I took a look at the content of these pages. A few thoughts:

- Overview topic: I think it needs to list the modules that you'd need to enable to do various types of tracking, and explain the difference between the types of tracking. The reason I say that is that if you don't have the modules enabled, you might not realize you need them enabled (see also Alona's comments in #16/17), so you would never learn about these types of tracking.

- other 3 topics: Probably they should all be turned into Task topics (following the template in the help topic standards)?

Anyway, I have to run out now, but I'll try to make a new patch in the next day or two to do those 2 things.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Needs work
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs work » Needs review
FileSize
interdiff.txt9.31 KB
3055317-28.patch6.33 KB

Here's a new patch. I ended up converting only 1 of the 3 specific topics to Task topics; the others didn't seem very task-like. But they're all (hopefully) conforming to the standards now.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
FileSize
interdiff.txt1.67 KB
3055317-29.patch6.38 KB

The Block module help topics were committed, so I've added the block placement topic as Related to the one topic in here that talks about block placement.

andypost’s picture

andypost
he/him
Primary language Russian
CreditAttribution: andypost as a volunteer and at Skilld commented
Issue tags: -Needs tests

Not sure it needs tests, maybe other issue to decide about testing a default set of topics
The issue just needs eyes to check wording (for non-native speaker it looks great) and RTBC

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

hah! You were the one who added the needs tests tag above. But now we have a test that verifies all existing topics at least have some content, are translated, etc. So I think we've taken care of that. :)

andypost’s picture

andypost
he/him
Primary language Russian
CreditAttribution: andypost as a volunteer and at Skilld commented

Yes! That's why I'm confident to remove it)
@jhodgdon Thanks for making "tracking" used, it's perfect term to use here

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I give credit to @batigolix for that. I just did a bit of rewriting and rearranging. :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Related issues: +#3090659: Make a way for help topics to generate links only if they work and are accessible
FileSize
3055317-34.patch6.37 KB
interdiff.txt1.62 KB

I just realized that we might have a problem with a link made from the statistics topic to the block layout page. If the Block module is not installed, that call to url() will fail and we'll have a Twig error. So, taking out that link, at least until #3090659: Make a way for help topics to generate links only if they work and are accessible is fixed.

Amber Himes Matz’s picture

Amber Himes Matz
she/her
Primary language English
Location Portland, OR USA
CreditAttribution: Amber Himes Matz at Drupalize.Me commented
Status: Needs review » Reviewed & tested by the community

The patch in #34 adds 4 new topics to core/modules/help_topics/help_topics/:

1. core.tracking_content.html.twig: Looks good.

2. history.tracking_user_content.html.twig: Looks good.

3. statistics.tracking_popular_content.html.twig: (Note: Install Statistics module to view this topic or to see it listed as related on other topics.) Looks good. Links verified.

4. tracker.tracking_changed_content.html.twig: (Note: Install Activity Tracker module to view this topic or to see it listed as related on other topics.) Looks good. Links verified.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott at Acro Commerce, Thunder commented
Version: 9.1.x-dev » 9.0.x-dev
Status: Reviewed & tested by the community » Fixed

Committed and pushed 70350eec55 to 9.1.x and 97552ce288 to 9.0.x. Thanks!

  • alexpott committed 70350ee on 9.1.x 
    Issue #3055317 by jhodgdon, andypost, batigolix, amarphule, alonaoneill...

  • alexpott committed 97552ce on 9.0.x 
    Issue #3055317 by jhodgdon, andypost, batigolix, amarphule, alonaoneill...

Status: Fixed » Closed (fixed)

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