Background:
This issue is part of the task to update the hook_help texts of the modules for Drupal 8:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- review if the text in aggregator_help() is up to date for Drupal 8
- test the links embedded in the text
- update d.o. docs at https://drupal.org/documentation/modules/action

The hook_help text for action needs a bit of updating: the copy is not according to the standards. There is a large chunk that appears on the admin page. (was it the purpose of hook_help to appear at random places? ) There is a chunk that is suppose to appear on a non existing page.
No link to online docs is provided

Files: 
CommentFileSizeAuthor
#26 action-help-permission-2030411-26.patch115 bytesifrik
PASSED: [[SimpleTest]]: [MySQL] 57,408 pass(es).
[ View ]
#21 action-help-text-2030411-21.patch2.3 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 57,289 pass(es).
[ View ]
#19 action-help-text-2030411-19.patch2.91 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 57,111 pass(es).
[ View ]
#17 action-help-text-2030411-17.patch5.75 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 57,017 pass(es).
[ View ]
#10 action-help-text-2030411-10.patch3.78 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 56,537 pass(es).
[ View ]
#9 action-help-text-2030411-9.patch3.79 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 56,900 pass(es).
[ View ]
#7 review-help-text-action-2030411-7.patch3.14 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 56,977 pass(es).
[ View ]
#6 review-help-text-action-2030411-6.patch3.13 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 56,387 pass(es).
[ View ]
#1 review-help-text-action-2030411-1.patch3.29 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,075 pass(es).
[ View ]

Comments

batigolix’s picture

StatusFileSize
new3.29 KB
PASSED: [[SimpleTest]]: [MySQL] 58,075 pass(es).
[ View ]

First modest attempt to fix the help text

batigolix’s picture

Status:Active» Needs review

set status

ifrik’s picture

Status:Needs review» Needs work

I tried to tidy up the language even more, because the issue of creating and configuring advanced modules appeared double. I would also propose to change the wording where you give examples of actions to match the actual wording used.

About
The Action module provides tasks that can be executed by the site such as unpublishing content, sending an email or blocking a user. Other modules can trigger these actions when specific system events happen; for example, when new content is posted or when a user logs in. Modules can also provide additional actions.
Simple actions do not require any additional configuration and are listed automatically on the Actions page. Advanced actions need to be created and configured individually.
For more information, see the online documentation.

Uses
Creating and configuring advance actions
Advanced actions can to be created on the Actions page, by selecting an action from the drop-down list. You can then configure your action, for example to send an e-mail to a specified address or to unpublish content containing pre-defined keywords.

jhodgdon’s picture

I like #3 generally... A few things will need to be fixed:
- Serial commas are needed: "a, b, or c" not "a, b or c".
- I think we have a standard format for referring to the online docs that includes the name of the module?
- Under Uses, the DT header should be "... advanced actions" not "advance actions".
- Another typo in the DD for that: "can to be".
- The wording in that DD is also a bit confusing. "actions can be created... by selecting an action...". Maybe the second "action" should be called an "action type" or something like that, to avoid saying "to create an action, select an action from the list", when "action" is kind of referring to two different things in that sentence?

ifrik’s picture

Assigned:Unassigned» ifrik
ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3.13 KB
PASSED: [[SimpleTest]]: [MySQL] 56,387 pass(es).
[ View ]

I've changed the text based on comments #3 and #4.
batigolix had proposed at another issue to have a standard sentence to refer to the online documentation to reduce the amount of translation, but then it's not possible to include the module name.

ifrik’s picture

StatusFileSize
new3.14 KB
PASSED: [[SimpleTest]]: [MySQL] 56,977 pass(es).
[ View ]

I've changed the link text to the online documentation following comment #10 and #11 in #2029737: Create hook_help() for ckeditor module

jhodgdon’s picture

Status:Needs review» Needs work

Looking better! A few things still to fix:

a) In About: "when a new content is posted" should not have "a" in there, or should say "a new content item"... probably best to just remove the "a"?

b) In Uses: "an automated email should be send." ==> sent

c) Do not remove these lines:

-
-    case 'admin/config/system/actions':
-    case 'admin/config/system/actions/manage':
...

Those provide help when you are on those particular admin pages.

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3.79 KB
PASSED: [[SimpleTest]]: [MySQL] 56,900 pass(es).
[ View ]

I've fixed the typos and shortened the link to the online documentation.
I've also edited the help text for the actions configuration text to be consistent with the text on the help page.
I've also edited the text for the admin/config/system/actions/configure text, but it doesn't show up where it should be - apparently that's a bug that needs fixing somewhere else.
With admin/config/system/actions/manage however I'm not sure where that text would show up, and therefore I can't check on whether it makes sense there.

(I wasn't sure how do partly revert the original patch, or how to properly do an inter-diff so I made a new patch.)

batigolix’s picture

StatusFileSize
new3.78 KB
PASSED: [[SimpleTest]]: [MySQL] 56,537 pass(es).
[ View ]
With admin/config/system/actions/manage however I'm not sure where that text would show up, and therefore I can't check on whether it makes sense there.

This path should be available when actions are defined for the website.

In the attached patched I changed the reference to the online docs so that it is in line with the other help texts.

Pancho’s picture

I'd make the "About" section shorter and move the description of the two types to the "Usage" section, so the that could possibly be:

Use simple actions
Simple actions do not require configuration and are listed automatically as available on the Actions page.
Creating and configuring Create and configure advanced actions
Advanced actions need to be created and are user-created and may be configured individually.
An advanced action can be created You create an advanced action on the Actions page by selecting an action type from the drop-down list. You can Then you may configure your action, for example by specifing the e-mail addressrecipient of an automated e-mail should be sent.
More information
For more information, see the online documentation for the Action module.
jhodgdon’s picture

Status:Needs review» Needs work

RE #11 - that does not conform to our standard help template. http://drupal.org/node/632280

RE patch in #10 - looks pretty good! A few typos:
- precise is misspelled in the last line of the patch (under case 'admin/config/system/actions/configure').
- The code indentation is wrong in case 'admin/config/system/actions/configure':
- Let's make sure that the text for case 'admin/config/system/actions/configure' matches what is on the screen -- is it called Label or Description or what? Probably capitalized?

Pancho’s picture

OK, so maybe like that:

About

The Action module provides tasks that can be executed by the site such as unpublishing content, sending an e-mail, or blocking a user. Other modules can trigger these actions when specific system events happen; for example, when new content is posted or when a user logs in. Modules can also provide additional actions. For more information, see the online documentation for the Action module.

Uses

Using simple actions
Simple actions do not require configuration and are listed automatically as available on the Actions page.
Creating and configuring advanced actions
Advanced actions are user-created and may be configured individually. You create an advanced action on the Actions page by selecting an action type from the drop-down list. Then you may configure your action, for example by specifing the recipient of an automated e-mail should be sent.

Think it's really better if the "About" section isn't too long.

jhodgdon’s picture

#13 looks fine to me, except the last clause of the last sentence, which needs editing: "by specifing the recipient of an automated e-mail should be sent".

ifrik’s picture

But the rewording of Advanced actions is not correct since none of the Advanced actions that can be created without configuring it.

Creating and configuring advanced actions
Advanced actions are user-created and have to be configured individually. You create an advanced action on the Actions page by selecting an action type from the drop-down list. Then you can configure your action, for example by specifing the recipient of an automated e-mail.
jhodgdon’s picture

RE #15 - OK, then take out "can" in "Then you can configure...". :) I would also take out "you"... so it would say:

Advanced actions are user-created and have to be configured individually. Create an advanced action on the Actions page by selecting an action type from the drop-down list. Then configure your action, for example by specifing the recipient of an automated e-mail message.

[note: e-mail is not a countable noun. Better to say "e-mail message". Or take out "an", so it says "recipient of automated email". And by the way I think we are changing the standard to "email" instead of "e-mail". There's an issue discussing it... I guess leave it as "e-mail" for now.]

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new5.75 KB
PASSED: [[SimpleTest]]: [MySQL] 57,017 pass(es).
[ View ]

Reworded according to the previous comments.
(And I'm not going to argue for the use of International English in which "email" is both the service as well as the individual message :)

jhodgdon’s picture

Status:Needs review» Needs work

RE: international English - Drupal documentation long ago adopted American standard English usage as its standard. I was not involved in that decision -- it predates my involvement in the project -- but that is what we use. See https://drupal.org/style-guide/content

This patch has the editor module in it... so it needs to be rerolled with just Action module.

And it should not be removing the help for the other admin pages... although it would be good if it was edited a bit too!

-    case 'admin/config/system/actions':
-    case 'admin/config/system/actions/manage':
-      $output = '<p>' . t('There are two types of actions: simple and advanced. Simple actions do not require any additional configuration and are listed here automatically. Advanced actions need to be created and configured before they can be used because they have options that need to be specified; for example, sending an e-mail to a specified address or unpublishing content containing certain words. To create an advanced action, select the action from the drop-down list in the advanced action section below and click the <em>Create</em> button.') . '</p>';
-      return $output;
-
-    case 'admin/config/system/actions/configure':
-      return t('An advanced action offers additional configuration options which may be filled out below. Changing the <em>Description</em> field is recommended in order to better identify the precise action taking place.');

But other than that, I think it's good! Please reroll the patch. Then, someone should please test it manually and make sure it formats well and that the links work.

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.91 KB
PASSED: [[SimpleTest]]: [MySQL] 57,111 pass(es).
[ View ]

attached patch:

- restores help for the other admin pages
- does not include editor.module
- has working links
- works in a local D8

jhodgdon’s picture

Status:Needs review» Needs work

That's great! The only thing is a few spaces crept onto the end of the line between the new help text and the old help text.

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.3 KB
PASSED: [[SimpleTest]]: [MySQL] 57,289 pass(es).
[ View ]

i think i found them

ifrik’s picture

Thanks batigolix for fixing that. I seem to have messed up my git branches when I worked on it.
Patch #21 works for me.

jhodgdon’s picture

Component:documentation» action.module
Status:Needs review» Reviewed & tested by the community

Looks good to me! I'll set it to RTBC and move it to the Action module component for review by the maintainers for a few days. If no one complains, I'll commit it.

Hm.. The action module is not in MAINTAINERS.txt. Hopefully it has maintainers...

alexpott’s picture

Status:Reviewed & tested by the community» Fixed

Committed b5f2341 and pushed to 8.x. Thanks!

ParisLiakos’s picture

Issue tags:+Needs followup
diff --git a/core/modules/action/action.module b/core/modules/action/action.module
old mode 100644
new mode 100755

needs a followup for this

ifrik’s picture

Status:Fixed» Needs review
StatusFileSize
new115 bytes
PASSED: [[SimpleTest]]: [MySQL] 57,408 pass(es).
[ View ]

Permissions changed to 644

ParisLiakos’s picture

Status:Needs review» Reviewed & tested by the community

thanks!

alexpott’s picture

Status:Reviewed & tested by the community» Fixed
Issue tags:-Needs followup

Committed fcf2c9d and pushed to 8.x. Thanks!

Status:Fixed» Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.