Update Help Text Standards Examples to Modify Heading Structure

Some additional information:

a) These standards are used for modules that implement hook_help().

b) Normally, this help is displayed on a page like
admin/help/link (for the Link module)
where, in the Seven theme, there is an H1 at the top for the page title ("Link"), and then in the main content region, the next header is the H3 saying "About". There is no H2 on the page, except in the Toolbar area, which is outside the hierarchy of the main content region.

c) The standards have been in place with a suggestion of an H3 for About, and an H3 for Uses, for about 9 years. They were adopted as "way better than what came before" (which was no headings at all, and no standard structure), without much discussion of the details of the struture, on this issue:
#537828: Help text for core modules - update to conform to new standard

I'll add these notes to the issue summary.

I am +1 for this change by the way.

Thanks for filing this, great issue summary.

After we update core modules hook_help(), a change record should explain this, and encourage contrib/custom modules to update theirs too.

So we can see how the proposed headings work out, this patch replaces H3 with H2 in hook_help() for modules beginning with A.

@jhodgdon - I see this issue is in coding standards project, but core patches would need to be against the drupal core project. Should we have a separate issue for the core patch? If we update the documentation page first, we could move this issue to the drupal core project afterwards.

One interesting thing I noticed is that some module help pages have a section for admin links. This list is generated automatically, and also has a H3.

This patch updates HelpController.php to make it use a H2 as well.

Before this patch:

After this patch:

RE #6, the normal course of action for coding standards issues is:

a) Get the community to agree on the coding standards change. (There's a defined process for that -- see the Coding Standards project page and links therein. https://www.drupal.org/project/coding_standards )

b) Formally adopt the coding standards change and update the coding standards documentation for it.

c) File a new Core issue and patch for coding standards.

Thanks, so the core patch will be a new issue. Meanwhile the patch in #7 at least demonstrates what we're proposing, but there's no need to finish it yet.

From the process:

At least two additional active community members (contrib module maintainers, active patch contributors, etc) need to agree to sponsor the change in the form of a comment on the issue.

Well it's +1 from me, then.

OK, then we have 2 active community members with +1 on this. I'll post a link in a couple of Slack channels to get more discussion, and we should leave this for a week or two to get more input if people are interested, and then we can tag with "needs announcement for final discussion".

+1 from me!

This gets a +1 from me too! Looks like a great idea.

This is great. What is needed to move this ahead?

Well, let's see -- the procedure is here: https://www.drupal.org/project/coding_standards

So it looks like we have finished the first two steps: create and issue and find at least 2 active people in the community who support it. So I think we can do step 3 and add the "needs announcement for final discussion" tag. Let's do it!

Ok, it looks like this is ready to go. We just need someone to make it happen. It's got the tag, how do we make it fixed?

Fixing tagging.

I am in favor of this change. According to Coding Standards, we should have completed #5. I don't see any update on #6 yet. How do we move this forward?

Added a patch for the heading change of help from h3 to h2 for below modules:

Action, Aggregator, AutomatedCron, Ban, Basic Auth, Big Pipe, Block, Block Place, Book, Breakpoint, CK Editor, Color

This patch has got heading changes for all core modules

This was discussed at a coding standards meeting. #3380936: Coding Standards Meeting 2023-08-01 2100 UTC where the following points were raised.

• This is referring to hook_help which is intended to be deprecated, #3031642: Deprecate hook_help() and combine with Topics.
• Should the Help Topic standards be withing the Coding standard wiki pages. What is the history for having them separate? Should they be moved?

I've updated the Issue Summary. In doing so I have removed two of the requested changes because that section of documentation, the example, was deleted. See https://www.drupal.org/node/632280/revisions/view/12277977/12369190

I now see that there is wiki page for 'Help Topic Standards'. I think these changes should also go there. Or is there a better way to have the same information in two places?

Setting to NW

Update the IS in preparation for announcing this one

This change is scriptable

core$ cat help.sh 
#!/bin/bash

# Path to the Drupal root directory.
DRUPAL_ROOT="/path/to/drupal"
DRUPAL_ROOT="."

# Function name pattern of hook implementations for hook_help.
HOOK_HELP_PATTERN='function .*_help'

# Find all files in the Drupal root directory.
find "$DRUPAL_ROOT" -type f -name "*.module" | while read -r file; do
    # Check if the file contains the implementation of hook_help.
    if grep -q "$HOOK_HELP_PATTERN" "$file"; then
        # Use sed to replace <h3> with <h2> in the hook_help implementation.
        sed -i "/${HOOK_HELP_PATTERN}/,/^}/{s/<h3>/<h2>/g; s/<\\/h3>/<\\/h2>/g;}" "$file"
        echo "Updated $file"
    fi
done

echo "Done replacing <h3> tags with <h2> in hook_help implementations."

This was discussed by the coding standards committee and we all agreed to do this.

I have updated the documentation per the issue summary.

We also agreed that this isn't a Coding Standards issue, so moving to the Core queue.

The followup to make the change is #3414263: Change help headings for WCAG 2.0

Adding credit for the discussion amongst some coding standing committee members.

The patches are woefully out of date, please open a merge request instead and let's work on this against 11.x there.

Oh I see, we are scripting the changes instead. But if we are doing that in another issue, what's this issue for - only updating docs?

Hiding the patches so they don't confuse others like they did to me.

The Needs Review Queue Bot tested this issue.

While you are making the above changes, we recommend that you convert this patch to a merge request. Merge requests are preferred over patches. Be sure to hide the old patch files as well. (Converting an issue to a merge request without other contributions to the issue will not receive credit.)

Yes, this is about documentation.

On reflection, the change record should be on this issue as it is the changing the Standards documentation.

I added a change record here.

Thank you, back to RTBC

@andypost, thank you!

The documentation is updated and the implementation issue is also complete. The remaining piece is to publish the CR and set this to Fixed. I double checked the docs and the CR and I don't see anything that needs to be changed. Since there has been no further feedback and even though I wrote the CR I am going to publish and set this to Fixed.

Thank you to everyone here for improving Drupal!