Problem/Motivation

The effort to create missing hook_help and update existing hook_help texts is well under way, see #1908570: [meta] Update or create hook_help() texts for D8 core modules

This started more than a year ago and in the meantime UI changes have been made.

We need to revisit all the help texts before the D8 release. Now would be a good time, since we've had a few Beta releases, and the UI is more stable than it was earlier.

Proposed resolution

Review the help topics for all Core modules. Make sure they're accurate, clear, and complete.

Also, each one should be checked to make sure that the corresponding page on drupal.org, which the help topic page should link to, has at least the text from the in-Drupal help topic on it.

Remaining tasks

Review instructions

For each Core module, the task to be done is:

  • Install an updated copy of Drupal 8, if you don't already have it installed. The Standard install profile is recommended. If you do not have an easy way to install Drupal 8 locally, consider using http://simplytest.me .
  • Choose a module from the list below that hasn't been reviewed yet.
  • Enable the module in question from the "Extend" page (admin/modules).
  • Go to the Help page (admin/help). Click on the module name to go to that help topic.
  • Read the topic and make sure the text is clear and understandable.
  • Check the links in the help topic, and make sure they all work.
  • Make sure that if user interface text is mentioned in the topic, it matches what you actually see in the user interface. For instance, it might say "Click the Foo button on the Bar page", and you would want to make sure that the button actually says "Foo" and the page title is actually "Bar".
  • See if you think that the help text is complete. Are there things this module does that are not covered? Are there confusing concepts on any of the pages provided by this module that should be covered in the help?
  • Click through to the "For more help, see the page on drupal.org" link, and verify that the page there has at least the information that was in the topic you viewed within Drupal. If not, click Edit on the page and copy in the text from the topic.
  • When you have finished, if there are no problems with the help topic text or links, come back to this issue and edit the Issue Summary. Put a note in for the module you reviewed with the date, and say that the help looked good. And put <del>...</del> tags around that line in the module list for extra emphasis.
  • If you found problems, file an issue with title like "Update hook_help() text for the Foo module". Explain the problems that need to be fixed. In the "Issue summary and relationships" section of your new issue:
    - Make sure that this issue is listed as "Related".
    - Make sure that #1908570: [meta] Update or create hook_help() texts for D8 core modules is listed as "Parent".
    - Use component "documentation", or the particular module (either one is fine).
    Then edit the issue summary on this issue, and add a note for that module saying "As of [date] - has open issue", so that people will know that module has been reviewed. And put <del>...</del> tags around that line in the module list for extra emphasis.

Module list

Here is a list of modules to be reviewed (modules whose machine name is significantly different from displayed name are noted with () in list):
Actions - Reviewed 15 April 2015 - looks good
Activity Tracker (tracker) - Reviewed 15 April - looks good
Aggregator - Reviewed 17 Jan 2015 - Looks good
Ban - Reviewed 17 Jan 2015 - Looks good
Block - Reviewed and committted on 14 April 2015
Book as of 15 April 2015 - has open issue
Breakpoint - Reviewed 14 April - looks good
CKEditor - Reviewed 14 April - looks good
Color - as of 17 Jan 2015 has open issue
Comment - Reviewed 14 April - looks good
Configuration Manager (config) - as of 12 November 2012 - has open issue
Configuration Translation (config_translation) - Reviewed 16 April 2015 - looks good
Contact - Reviewed and committed on 14 April 2015
Content Translation - Reviewed 16 Aprils - looks good
Contextual Links (contextual) - Reviewed 14 April 2015
Custom Block (block_content) - Reviewed - committed on 15 Aprils 2015
Custom Menu Links (menu_link_content) - as of 18 April 2015 - has open issue
Database Logging (dblog) - Reviewed 14 April 2015 - looks good
Datetime
Entity Reference - Reviewed and Committed on 15 April 2015
Field- as of 23 Dec 2014 - has open issue
Field UI - as of 23 Dec 2014 - has open issue
File - Reviewed 14 April 2015 - looks good
Filter - Reviewed and committed on 15 April
Forum - as of 15 April 2015 - has new issue
HAL - Reviewed 16 April 2015 - looks good
Help - Reviewed 14 April 2015 - looks good
History - Reviewed 14 April 2015 - looks good
HTTP Basic Authentication (basic_auth) - Reviewed 16 April 2015
Image - as of 26 Nov 2014 - has open issue
Internal Page Cache (page_cache) - as of 17 April 2015 - has open issue
Language - Reviewed 16 April - looks good
Link - Reviewed and Committed on 15 April
Interface Translation (locale) - Reviewed 16 April - see comment #53
Menu UI
Migrate Drupal - Reviewed and committed on 18 April 2015
Migrate - Reviewed and committed on 18 April 2015
Node - Reviewed and Committed on 15 April
Options - Reviewed 14 April - looks good
Path - as of 14 April 2015 - has open issue
Quick Edit - Reviewed 14 April - looks good
RDF - Reviewed and committed on 15 April 2015
Responsive Image - Reviewed 16 April - looks good
RESTful Web Services (rest) - Reviewed 16 April 2015
Search - Reviewed 15 April - looks good
Serialization - Reviewed 16 April - looks good
Shortcut - Reviewed and Committed on 15 April 2015
Statistics - Reviewed and Committed on 17 April
Syslog - Rewiewed 16 April - looks good
System - as of 26 Nov 2014 - has open issue
Testing (simpletest) - Reviewed 19 April 2015 - looks good, but has open issue as of 19 April
Taxonomy - as of 26 Nov 2014 - has open issue
Telephone - Reviewed 16 April 2015 - looks good
Text - Reviewed and committed on 17 April 2015
Text Editor (editor) - Reviewed 15 April 2015 - looks good
Toolbar - Reviewed 15 April - Due to a bug, the toolbar cannot be switched from vertical to horizontal. Help only needs to be updated if that is not fixed #2424805: Toolbar can no longer switch horizontal and vertical -- expects breakpoints ordered from smallest to largest; responsive images need largest to smallest
Tour - Reviewed 16 April 2016 - has open issue
Update Manager (update) - Reviewed and committed on 17 April 2015
User - Reviewed 15 April 2015 - looks good
Views - Reviewed 15 April 2015 - looks good
Views UI - Reviewed 15 April 2015 - see comment #45

User interface changes

Help pages would be improved as needed.

API changes

None.

Comments

batigolix’s picture

batigolix’s picture

Issue summary:View changes
batigolix’s picture

Title:Review references to UI in hook_help texts» Review hook_help texts & copy text to drupal.org
Issue summary:View changes
batigolix’s picture

Issue tags:+sprint, +documentation
batigolix’s picture

Issue summary:View changes
jhodgdon’s picture

Why is this a separate issue from the original one? I would prefer to have just one issue to go to to see if we need to review/commit any more changes to help, rather than two separate issues.

Also, maintaining a list of issues in the issue summary is tedious. Now that we have "related issues" I prefer just to have issues listed as parent/related so they appear automatically on the sidebar...

jhodgdon’s picture

Title:Review hook_help texts & copy text to drupal.org» [META] Review hook_help texts & copy text to drupal.org
jhodgdon’s picture

Issue summary:View changes

This is the right time to do this, since we're in "Beta" and features are frozen.

Here's what I'd like to suggest. Rather than filing "review" child issues for each module right now, let's maintain a list of modules in the issue summary, and as they get reviewed, we can update the list with the date.

Any problems we find in the review should be filed as new issues (if there isn't already an open issue for that module) and the issues need to be given "parent" equal to #1908570: [meta] Update or create hook_help() texts for D8 core modules. If there's a currently open issue for the module already, I think we don't need to give it another review now because it should be reviewed before that issue is resolved.

Then later we can go through and make sure the text is also copied to drupal.org, maybe when we have all the help updated.

OK?

Also I updated the module list in the summary. It is now complete. I think it is highly unlikely more modules will be added at this point.

jhodgdon’s picture

Issue summary:View changes

Added notes " - as of 26 Nov 2014 - has open issue" for modules that currently have open "Update hook_help()" issues.

jhodgdon’s picture

Issue summary:View changes

Two more...

xjm’s picture

Issue tags:-revisit before release+revisit before release candidate
jhodgdon’s picture

Issue summary:View changes

Added contributor instructions to this issue and made a proper issue summary.

jhodgdon’s picture

Issue summary:View changes

One more minor edit.

jhodgdon’s picture

Issue summary:View changes

Updating summary because Field is on the Field UI issue.

jhodgdon’s picture

ifrik’s picture

Identifying this as a potential good issue for Sprint Weekend. See discussion at #2407325: preparing for a sprint, would be good to have a list of candidate issues.

develCuy’s picture

develCuy’s picture

Removed SprintWeekend2015Queue by mistake.

Sara.Smith’s picture

Issue summary:View changes
stpaultim’s picture

Issue summary:View changes

I checked the DateTime module and it looks good to me.

pythagory’s picture

Issue summary:View changes

Reviewed Aggregator help text, looks good.

pythagory’s picture

Issue summary:View changes
TechnoTim2010’s picture

I looked at Entity Reference, using Beta4 on SimplyTest.me, raised an issue https://www.drupal.org/node/2408715 as I found it referred to the Entity module, which is in core, then tried to create a patch, cloned d8 dev did the simple edit, created the patch, but it failed testing. So I wiped clean pulled a new dev checked core/modules/entity_reference.module line 25 and the change was already in place. I only ever committed to my branch. Anyone suggest where I went wrong. BTW this was intended as my first commit.

Tim

ifrik’s picture

Issue summary:View changes
ifrik’s picture

ifrik’s picture

Issue summary:View changes
ifrik’s picture

The Configuration Management still has a major open issue, that is currently postponed #1831798: Update hook_help() for config manager module

ifrik’s picture

Issue summary:View changes

Sorry, I didn't read the description for this issue correctly and removed <del> tags on two modules where I shouldn't have. I've added them back.

ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
Issue tags:+drupaldevdays
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes

Views UI: I can't actually see the option for theming views that is described in the last Use.

For the rest the help looks good.

ifrik’s picture

(Activity) Tracker module: The listing provided by tracker module refers to "replies" instead of comments. I filed an issue to change that. If it gets fixed, then the help text is correct, if not then the help needs changing #2471729: Tracker module refers to replies instead of comments.

If the tracker listing is replaced by a View, then the help text needs review again #1941830: Convert tracker listings to a view.

ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes

The User Interface Translation Settings page is one of the currently six pages that are titled "Settings" if that gets changed the help text will need to be changed as well.

ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes

The testing module cannot be enabled if a curl library is missing but the provided link to php.net is not useful enough.

ifrik’s picture

Issue summary:View changes
ifrik’s picture

All modules listed here have been reviewed as of 16 April, and new issues have been opened as appropriato as child issues of #1908570: [meta] Update or create hook_help() texts for D8 core modules.

jhodgdon’s picture

Status:Active» Fixed

OMG ifrik I cannot believe you got through everything!!!!!! Thanks! I think we can mark this issue as Fixed in this case.

jhodgdon’s picture

Issue summary:View changes
Status:Fixed» Active

@tstoeckler just told me about a new module that got committed about 5 minutes ago. It has hook_help() but the module name and help are not using Proper Case and in any case it probably needs a review.

It's the "Internal Page Cache" module.

I guess we may have had some help in the System module help about page caching that would need to be moved there too? Probably this was not done in the patch? Anyway... needs review, adding to summary and I'll go through the current list of modules and make sure they are all listed in the summary. [OK, just that one was missing]

tstoeckler’s picture

ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

I'm changing the annotation for any modules that are fixed, even though all should be linked from #1908570: [meta] Update or create hook_help() texts for D8 core modules anyway.

ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
ifrik’s picture

Issue summary:View changes
webchick’s picture

So while there are a couple of things left to do here, I discussed this with jhodgdon and we both agreed that this doesn't need to hold up RC. These sorts of documentation fixes are exactly the things we can and should be comitting during RC.

Removing the tag.