This issue is part of the task to update the hook_help texts of the Drupal 8 modules:#1908570: [meta] Update or create hook_help() texts for D8 core modules
- review / write the hook_help text according to help guidelines
- review online docs https://drupal.org/documentation/modules/color
- changed link to online docs
- removed some "marketing" speak ("fast & easy")
I'm wondering if we can remove some text such as the warning:
This means that if you make any manual changes to your theme's stylesheet, <em>you must save your color settings again, even if they haven't changed</em>. This step is required because the module stylesheets (in the files directory) need to be recreated to include your changes.")
I'm unsure if such advice should be part of the hook_help or should be on line.
I think the note about the files important enough to be in the hook_help. The hook_help should have all necessary information, because not everyone is necessarily connected to the Internet at all times.
By the way, batigolix -- didn't the standard for referring to the online documentation previously say "For more information, see the online documentation for the Foo module"? I'm wondering if when you changed it to have its own t(), you took out the "for the Foo module" piece? If so, let's put it back. The problem is that the "online documentation" link is not very good for accessibility purposes -- the link text does not describe where the link really goes (it is non-specific).
Regarding the rest of the help text, it looks pretty good... a few things I think should be fixed:
- Be sure to refer to "the Color module" not "the color module" throughout.
- We should verify that the permission names are still accurate, and that this is the permission the Color module actually checks.
- Normally when we have URLs referred to in hook_help() or in API documentation, we'd prefer that the page being linked to has a URL alias rather than just node/12345
- URLs on drupal.org are now https not http
I've given this issue a second thought.
This help text was already reviewed for Drupal 7. I'm sure we can find small things to improve.
But we can better concentrate on the modules that, at the moment, have no or poor hook_help texts.
A second worry is that small change in UI strings destroy existing translations. Especially the help texts are long strings that are hard to translate. If we fine tune all existing help texts we will make many translators (including me) unhappy.
Regarding the standard for referring to the online documentation: yes, it was my plan to have a general sentence for this, without mentioning the modules name. Given my doubts above, I think it is best to stick to the old standard. Ill revert the changes in https://drupal.org/node/632280
So, shall we postpone this issue?
Tagging for my exposure
There is no reason to leave this as "postponed" at this point.
Patch addresses the points in #2
I removed the troubleshooting reference
This looks fine to me.
I think it's ready for a manual test:
- Make sure all the links work
- Make sure any permissions, page names, and other text appearing in the user interface are the same in the help text as what the admin would actually see in Drupal
- Make sure formatting is OK.
Also, the color.module maintainers should respond here that they're happy with the accuracy of the help, hopefully.
Manually tested. Looks good, color.module maintainer signs off.
- Links work, I made one very small change to one of the links though:<a href="!appearance">Appearance page</a> to <a href="!appearance">Appearance</a> page
- Permission, page names and other text appear correct
- Formatting is ok (follows same formatting as other help pages).
<a href="!appearance">Appearance page</a>
<a href="!appearance">Appearance</a> page
Leaving as CNR so testbot picks up, RTBC when it comes back green.
Great, thanks! Moving back to Documentation component so I will get it committed next time I'm doing commits, unless somoene else gets to it before me.
Thanks again! Committed to 8.x.
Automatically closed - issue fixed for 2 weeks with no activity.
This issue has no child issues.
Drupal is a registered trademark of Dries Buytaert.