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
Activity Tracker (tracker)
Aggregator - Reviewed 17 Jan 2015 - Looks good
Ban - Reviewed 17 Jan 2015 - Looks good
Block - as of 26 Nov 2014 - has open issue
Book
Breakpoint
CKEditor
Color - as of 17 Jan 2015 has open issue
Comment
Configuration Manager (config) - as of 26 Nov 2014 - has open issue
Configuration Translation (config_translation)
Contact - as of 26 Nov 2014 - has open issue
Content Translation
Contextual Links (contextual)
Custom Block (block_content) - as of 26 Nov 2014 - has open issue
Custom Menu Links (menu_link_content)
Database Logging (dblog)
Datetime
Entity Reference
Field- as of 23 Dec 2014 - has open issue
Field UI - as of 23 Dec 2014 - has open issue
File
Filter
Forum
HAL
Help
History
HTTP Basic Authentication (basic_auth)
Image - as of 26 Nov 2014 - has open issue
Language
Link
Interface Translation (locale)
Menu UI
Migrate Drupal - as of 26 Nov 2014 - has open issue
Migrate - as of 26 Nov 2014 - has open issue
Node
Options
Path
Quick Edit
RDF
Responsive Image
RESTful Web Services (rest)
Search
Serialization
Shortcut
Statistics
Syslog
System - as of 26 Nov 2014 - has open issue
Testing (simpletest)
Taxonomy - as of 26 Nov 2014 - has open issue
Telephone
Text
Text Editor (editor)
Toolbar
Tour
Update Manager (update) - as of 26 Nov 2014 - has open issue
User
Views
Views UI

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