Problem/Motivation

There are quite a lot of new modules in Drupal 8.x without any hook_help() text (displayed by the Drupal Core Help module -- link can be found on the Modules list admin page). Also, many of the existing modules functionality has changed or been split up, and the hook_help() text from Drupal 7.x still in 8.x does not reflect this. In some cases, the module descriptions (in the .info files, displayed on the admin Modules list page) may also be incorrect.

Proposed resolution

On this meta-issue, we need to review each Drupal 8.x core module (see list below) and check for:

  1. Proofreading: Good grammar, clear writing, correct punctuation and spelling etc.
  2. Standards: Follows our standard help template, including correct URL syntax -- see http://drupal.org/node/632280
  3. Function: If there is already a patch, apply the patch. If not, test the existing help page. Test all the links manually to see if they go to the right place, and make sure that the formatting looks OK. You should be able to get to the help by navigating to admin/help and finding the module name in the list.
  4. Accuracy: Read the help text vs trying out what it tells you to do and make sure it's correct, and that page titles, field labels, tab labels, etc. that you see on the screen match with what is in the help text.

If you review a patch or an existing help page for any or all of the above, add a comment to the issue telling what you have checked. If you checked all 4 and it looks good, set the status to "reviewed and tested by the community" if there is a patch, and if it is still a "review existing help text" issue, add a note that the existing help is fine and mark the issue as "fixed".

Remaining tasks

All of the modules in the list below need to have issues, and all of them need to get to "fixed" status:

action: #2030411: Update hook_help for action module #2091281: change link format in hook_help in Action module
aggregator: #1977608: Update hook_help Aggregator module
ban: #1977644: Update hook_help Ban module#2091285: Change link format in hook_help in Ban module
basic_auth: #2103035: Review/update hook_help() for the basic_auth module
block: #2029731: Improve help for blocks module (also #2062761: Update hook_help() for custom_block modules for possible comments)
book: #2091385: Update hook_help for Book module
breakpoint: #2091297: Update hook_help for Breakpoint module
ckeditor: #2029737: Create hook_help() for ckeditor module #2097545: Change link format in hook_help in CKEditor module
color: #2031639: Update hook_help for Color module
comment : #2091299: Update hook_help for Comment module
config: #1831798: Improve help text and documentation for CMI imports
config_translation: #2161801: Update hook_help for Config translation module
contact: #2091395: Update hook_help for Contact module
content_translation: #2091479: Update hook_help for content_translation module
contextual: #2091311: Update hook_help for Contextual Link module
custom block: #2062761: Update hook_help() for custom_block modules
datetime: #2091397: Create hook_help for Datetime module
dblog: #2091315: Update hook_help for Database Logging module
edit: #2091401: [PP-2] Add hook_help for Edit module
editor: #2031743: Improve hook_help for text editor module and #2033471: Mention core WYSIWYG / CKEditor in editor_help() and #2091377: Change link format in hook_help in Text Editor module
email: #2030713: Improve help for email module
entity: #2091403: Create hook_help for Entity module
entity_reference: #2029751: Create hook_help for entity reference
field: #2091319: Update hook_help for Field module
field_ui: #2091321: Update hook_help for Field UI module
file: #2031177: Improve help for file module
filter: #2041701: Update hook_help for filter module
forum: #2091455: Update hook_help for Forum module
hal: #2029755: Create hook_help for HAL module
help: #2091335: Update hook_help in Help module #1387964: People miss the first section of the help overview page
history: #2029767: Improve hook_help for history module
image: #2091337: Update hook_help for Image module
language: #2103039: Review hook_help for the language module
link: #2028799: Improve help for link module
interface translation: #2091459: Update hook_help for Locale module
menu: #2090525: Update hook_help for menu module
menu_link: #2033413: Create hook_help for Menu link module
migrate: #2161793: Create hook_help for migrate module
migrate_drupal: #2161797: Create hook_help for migrate drupal module
node: #2091343: Update hook_help for Node module
number: #2091345: Update hook_help for Number module
options: #2091347: Update hook_help for Options module
overlay: #2091349: Update hook_help for Overlay module
path: #2091353: Update hook_help for Path module
responsive images: #2033415: Review hook_help for Picture module
rdf: #2091357: Update hook_help for RDF module
rest: #2091415: Update hook_help for Restful Web Services module
search: #2091359: Update hook_help for Search module
serialization: #2036689: Create hook_help for Serialization module
shortcut: #2091361: Update hook_help for Shortcut module
simpletest: #2103041: Review hook_help for simpletest.module
statistics: #2091419: Update hook_help for Statistics module
syslog: #2091425: Update hook_help for Syslog module
system: #2091363: Update hook_help for System module
taxonomy: #2091367: Update hook_help for Taxonomy module
telephone: #2078813: Create hook_help for telephone module
text: #2091461: Update hook_help for Text module
toolbar: #2091379: Update hook_help for Toolbar module
tour: #2035145: Create hook_help for Tour module
tracker: #2091429: Create hook_help for Tracker module
update: #2091431: Update hook_help for Update Manager module
user: #2103043: Review hook_help for the user module (see also: #1952064: Shorten help text on User Roles page)
views: #1876904: Implement hook_help() for views.module
views_ui: #1876906: Implement hook_help() for views_ui.module
xmlrpc: #2103045: Review hook_help for xmlrpc.module

Files: 
CommentFileSizeAuthor
#21 ModuleExtendPage.png62.38 KBStuartJNCC

Comments

As a note: this should have been done when the modules were split up: http://drupal.org/core-gates -- and we should as part of this effort also review the module descriptions in the .info files (which appear on the Modules page).

Issue summary:View changes

added a list of d8 modules for listing issues

Issue tags:+Novice

I've updated the issue summary and made a table. This should be a good Novice project (reviewing the modules and filing issues) I think? If you review a module, update the table in the issue summary. Thanks!

It may be good to keep this on hold for a moment until the outcome of these discussions is clear:

#1920470: Find out how help and tour can work together
#1918856: Put each module's help into a separate Twig file

I disagree on putting this issue on hold -- at least we can survey whether the help is there or not and what needs updating?

If we use twig templates, we'll still need updated text.

Tours... that would require a lot of content development that I doubt will happen, and it looks like we would probably still need some help text?

In the meantime we will still need descriptions of what these modules do, and this issue is mostly about doing a survey, which is still appropriate.

Agree with everything but we must keep a close eye on the development of the Tour module.

Meta issue #1921152: META: Start providing tour tips for other core modules. deal with creating tour tips.

Issue summary:View changes

Make nice issue summary with actual actionable tasks in it

I checked the first three modules (action, aggregator, ban) and updated the issue summary.

I replaced the table markup (apologies) in the summary because I cant write text sprinkled with table markup. I have a particular kind of

blindness caused by staring at HTML source code too long.

I will create issues for these three modules as test cases. Working on them we can find out if the guidelines are still OK, what the state of the d.o. docs is and so forth.

For reference, this is what the meta issue for updating the hook_helps for Drupal 7 looked like: #537828: Help text for core modules - update to conform to new standard

Issue summary:View changes

reviewed 3 modules. replaced table markup

Issue tags:+d8docs, +d8help

- created an issue for updating the hook_help text of the the aggregator module #1977608: Update hook_help Aggregator module

- added a tag #d8help (in line with #d7help) to track hook_help related issues

Issue summary:View changes

issue aggregator

Issue for improving the hook_help of link module : https://drupal.org/node/2028799

Issue summary:View changes

issue ban module

Issue summary:View changes

added link to link help issue

Issue summary:View changes

update list

Issue summary:View changes

updating list

Issue summary:View changes

removed openid

Issue summary:View changes

link to issue for the block help page added

Issue summary:View changes

ckeditor

Issue summary:View changes

ent ref link

Issue summary:View changes

hal

Issue summary:View changes

history module

The list in the issue summary was updated during the code sprint in Dublin

Title:[meta] hook_help() text is seriously out of date and/or missing in most modules[meta] Update or create hook_help() texts for D8 core modules

added some precision tot the title

Issue summary:View changes

layout

Issue summary:View changes

updated list

As a note... Any hook_help that needs to refer to "entities" or "fieldable entities" or "bundles" should be postponed at this point until we have decided on how to refer to them in a standard way on this issue:
#2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI

I have already postponed the Link and Entity Reference help on this basis.

Issue summary:View changes

action module

If you add new modules to this meta-issue, please make sure they refer back to this issue and to the help guildelines. Thanks!

A good template would be
#1977608: Update hook_help Aggregator module

Issue summary:View changes

added link for email

Issue summary:View changes

added file issue

Issue summary:View changes

color module

Issue summary:View changes

Text editor issue added

Issue summary:View changes

picture, menu link and layout

Issue summary:View changes

links to issue about help text user module

Issue summary:View changes

Added editor.module and the corresponding issue.

Issue summary:View changes

bringing the two (text) editor issues together

Issue summary:View changes

Undo the last edit. The list goes by internal module names.

Issue summary:View changes

serial

Issue summary:View changes

added link for filter module

Issue summary:View changes

Updated issue summary.

Issue summary:View changes

added link for telephone module

I found #1876906: Implement hook_help() for views_ui.module today and added it to this list. The module wasn't even in the list... can someone go through and make sure the list above is the same as the list of what modules we actually currently have in core?

Also, on that same issue... We need to update the standards for hook_help to use the URL generator class instead of url(), apparently. And we should be using ! instead of @ for URLs apparently. See comments #21-24.

I have just updated the help standards for these two issues:
https://drupal.org/node/632280

So

$output .= '<p>' . t('The Content Translation module allows content to be translated into different languages. Working with the <a href="!locale">Locale module</a> (which manages enabled languages and provides translation for the site interface), the Content Translation module is key to creating and maintaining translated site content. For more information, see <a href="!translation">the online documentation for the Content Translation module</a>.', array('!locale' => url('admin/help/locale'), '!translation' => 'http://drupal.org/documentation/modules/translation/')) . '</p>';

should become:

$generator = Drupal::urlGenerator();
$output .= '<p>' . t('The Content Translation module allows content to be translated into different languages. Working with the <a href="!locale">Locale module</a> (which manages enabled languages and provides translation for the site interface), the Content Translation module is key to creating and maintaining translated site content. For more information, see <a href="!translation">the online documentation for the Content Translation module</a>.', array('!locale' => $generator->generate('admin/help/locale'), '!translation' => 'http://drupal.org/documentation/modules/translation/')) . '</p>';

?

Well, no, not quite... I guess I got the docs page wrong. And I'm not sure what the answer is, so I have asked it at
#1876906-26: Implement hook_help() for views_ui.module
because that is the first I saw of "do not use url() any more" on one of these issues.

Old
url('admin/help/' . $module_name)
New
Drupal::url('help_page', array('name' => $module_name))

Thanks, I will update the help page.

NOTE: tim.plunkett says that at this moment, that Drupal::url() formulation is slightly broken due to a typo in the code... it should hopefully be fixed very soon. See
#2078285-12: Add short-cut methods to the \Drupal class for generating URLs and links from routes
(you can make that change in your own site for testing purposes)

Also, as a note: if you need to make a link to an admin page, you will need to figure out the "route machine name" of the page. These are located in the routing.yml files. For instance, to find the route to the admin/structure/views page, you would find the views_ui.routing.yml file and see this:

views_ui.list:
  pattern: '/admin/structure/views'

That tells you the route machine name is "views_ui.list", and then to make a URL to it, you would do:
Drupal::url('views_ui.list')

So. There we have it: an answer. Hope that's clear... I'll go update the help standards page now.

I have attempted to put this in the help standards here:
https://drupal.org/node/632280#url-note
Hopefully it is clear enough...

Great, forgot the other url() shortcut method was added (Just wraps what we talked about above). The params are also fixed now.

StatusFileSize
new62.38 KB

Fixes to add help for Action (#2030411: Update hook_help for action module committed 24 July) and Ban (#1977644: Update hook_help Ban module committed 17 July) have both apparently gone in, yet when I checked today (using install of latest HEAD) I don't see "Help" links for either of these modules appearing on the "Extend" page.

Extends page screenshot

Issue summary:View changes

Added views_ui

Issue summary:View changes

add menu module issue

Issue summary:View changes

Added new issues for action and ban module to change link formats

Issue summary:View changes

Added issues for modules

Issue summary:View changes

Added issues for modules

Issue summary:View changes

Updated issue summary.

Issue summary:View changes

Added more modules

I've filled the rest of the list in, including new issues for hook_help texts that have already gone in, but now need their links changed.

Issue summary:View changes

added even more issues

Issue summary:View changes

Layout module is no longer in core.

Regarding #19:

I get errors if I use:

\Drupal::url('help_page', array('name' => 'module_name'))

It seems that name of the routing should be help.page instead of help_page (according to help.routing.yaml)

Maybe this changed recently?

Yes, that did change recently. All route names are now modulename.something_else, and so it is now help.page

For everyone to understand the ! vs @ and put us on the same page, String Formatters. We should be using ! since the urls passed to the link tags are in code and already pre formatted to display as intended.

Issue summary:View changes

Two layout listings

Issue summary:View changes

tour issue

Issue summary:View changes

Added issue for the block module

Issue summary:View changes

Updated issue summary.

@jhodgdon

Jennifer and everybody else,
Do you have suggestions for priorities which of these texts to work on first during the DrupalCon sprint tomorrow?
Or ideas which modules might still change so much, that the texts probably will need re-doing anyway?

Yes. My suggestion:

a) Any of the above issues that are in "needs review" status - get people going on reviewing those patches. They all need to be checked to see that (a) they make sense (b) they are using correct grammar, punctuation, spelling, etc. (c) the links all work correctly (d) they follow our help text guidelines and (d) they match what Drupal's user interface shows.

b) Beyond that, we really need to get the Field, Field UI, and Entity module help written. Maybe a couple of people could work together on making sure the wording for each one is good? I've just added notes to all of those issues about what needs to be said... well hopefully! All of the individual field modules are linking to Field and Field UI modules, which need to explain what fields are (Field) and how to manage them (Field UI). And those two need to link to Entity for an explanation of what entities are.

c) The System module needs to have an explanation of the file system setup, if it doesn't have it already (private vs. public files). The File and Image modules are going to be depending on this.

d) Above all... Try to help each person find a task that is appropriate, and/or get people working together. All of the help needs to be done, so if someone is nervous, make sure they're working on a module they use and understand, or that they are working with another person or sitting near people who can help. There is no reason that two or three people can't work on a patch together, and the great thing about an in-person sprint is that you can be sitting next to people who can help each other, proofread each other's text, etc. Maybe someone there is a great proofreader, and can be the official roving proofreader for the sprint, even though they don't want to learn how to make patches. Maybe someone who is a good writer and knows a lot about building Drupal sites can work with someone who knows how to make patches, so between them they can write a great help text and get it into a patch. You get the idea. :)

e) THANKS for organizing this sprint!!!!!!

Oh, and I don't know of any modules that are going to be changing a lot from here on out. I updated the list of modules in the summary a few days ago, so I think the list above is complete and correct.

Issue summary:View changes

Update list of modules to what is actually in core

Issue summary:View changes

Updated issue summary.

Issue summary:View changes

Added another issue dealing with help text in the help module

Issue summary:View changes

Clarify the review task. Also I filed issues for the remaining modules.

Why this is major and sub issues are critical? It should be vice verse.

A few sub-issues are critical - the ones for modules that are completely missing hook_help(), which is a violation of standards.

Most of the sub-issues are normal - the ones for modules that just need an update, which is appropriate.

The meta-task here is major because we want to make sure it gets done before release, but we don't want a huge number of major issues open to skew the statistics on how much code work needs to be done.

I think it's all where it should be...

Issue summary:View changes

translation module does not exist

Issue summary:View changes

Cleaning up sub-tasks

Issue summary:View changes

Updating sub-task format...

Umm... That is a nice idea, but that means whenever an issue gets fixed we need to go back here and update the list. I think we should revert back to how the list was before and just let the issue status highlighting indicate which items are done and which aren't. This is too hard to maintain. And also the list isn't right, and it seems to now have a few unrelated issues in it.

@jhodgdon updated this issue so that we know exactly what is done and what is pending.

but that means whenever an issue gets fixed we need to go back here and update the list

We don't need to update meta after done with every issue. It can be updated once the considerable number of issues are fixed (in other words, when the remaining list looks messy to select the one available). As you can see in config schema meta (https://drupal.org/node/1910624#round1 https://drupal.org/node/1910624#round2, https://drupal.org/node/1910624#round3), we can move them to completed list.

the list isn't right, and it seems to now have a few unrelated issues in it.

I just selected them from the list which was there before. Feel free to update, if anything wrong/mis-placed.

In the Action module line there is:
#2002726: Remove unused local variables from core/includes/menu.inc which must be the wrong issue number I think?

Anyway can you **please** put this list back to how it was? It is much better in my opinion to have one list to scan than two, so we can make sure all the modules are covered. New modules keep getting added to core, and others removed. Having two lists is annoying, and I really don't want to have to *ever* edit the lists there to move things from "to do" to "done" when the issue status will tell us at a glance if they are finished or not. Look at the list you have made -- several of the "done" items are not, and several of the "not done" items are done. It's just not very good.

Please? please? please?

Issue summary:View changes

restoring the sub-task list at #31.0

Thank you very much!

You are welcome. Sorry didn't mean to mess the list.
We got a code sprint this weekend (around 10 different locations), thought of getting the todo list explicit to make sprint more effective :)

Yes... a good idea in principle, but in practice if the list becomes less accurate, and harder to maintain, and if some of the items are in the wrong part of the list... it is just easier and safer to scan down the single, automatically-updated list, to see which items are still at "needs review" or "needs work" or "active".

So I hope your code sprint goes well! There are quite a few Help text issues that need manual testing (those are in "needs review" status), so that would be a great place to start for people who are new to hook_help() and the standards.

Also most of the ones that are in "needs work" status just need a few small fixes, so those would be a good place to put people who are ready to make a patch.

Thanks!

So I hope your code sprint goes well! There are quite a few Help text issues that need manual testing (those are in "needs review" status), so that would be a great place to start for people who are new to hook_help() and the standards.

Also most of the ones that are in "needs work" status just need a few small fixes, so those would be a good place to put people who are ready to make a patch.

awesome, thanks!!!

Issue summary:View changes

Add a few more missing modules to the list (modules added to Core recently). They need issues but at least they are in the list now.

Issue summary:View changes

Adding:

- config translation
- migrate
- migrate drupal

Issue summary:View changes

Hi folks, just a pointer to #1918856: Put each module's help into a separate Twig file where we're discussing alternate approaches for compiling the main help contents for a module (ie that shown in the /admin/help/ and admin/help/{module})

Please chime in over there if that sounds interesting to you.

Issue summary:View changes