Background:
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

Tasks:
- review / write the hook_help text according to help guidelines

Files: 
CommentFileSizeAuthor
#15 drupal8update-help-text-2091431-14.patch6.44 KBbatigolix
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 78,633 pass(es).
[ View ]
#10 drupal8update-help-text-2091431-10.patch6.52 KBInternetDevels
PASSED: [[SimpleTest]]: [MySQL] 60,008 pass(es).
[ View ]
#10 interdiff-2091431-8-10.txt2.58 KBInternetDevels

Comments

wzoom’s picture

Taking it... DrupalCon Prague

wzoom’s picture

Status:Active» Needs review
StatusFileSize
new6.54 KB
PASSED: [[SimpleTest]]: [MySQL] 58,656 pass(es).
[ View ]

Fixed url() -> Drupal::url().
Also changed mention about access rights (near FTP/SSH).

I think the "Install new theme" link is missing from the top of the themes page (/admin/appearance/install). But it is actually mentioned in the Help. Either there should be the button (which is not), or the sentence should be fixed (so that the button is not mentioned there).
But I don't know what is the right solution for that. Could you help me?

jhodgdon’s picture

Component:documentation» update.module

I do not know what the right answer is. Probably we should change the component here to the update module and hopefully the maintainers can answer the question.

batigolix’s picture

Status:Needs review» Needs work

a) should we remove the second reference to the on line docs in the 2nd point of the Uses section?

More detailed instructions can be found in the online documentation for Update Manager module.

This reference is already present in the about section conform the guidelines.

b) In my local D8 version the Install new theme buttons is also missing. I think it is because of this bug #2102357: “Install new theme” action link appears on /admin, which seems almost fixed. So we can assume that this link/button will be back in the near future.

I verified that all links work

wzoom’s picture

Status:Needs work» Needs review
StatusFileSize
new6.37 KB
new6.37 KB
PASSED: [[SimpleTest]]: [MySQL] 59,091 pass(es).
[ View ]

Ok, I removed the 2nd notice about online docs.

batigolix’s picture

Title:Update hook_help for Update module» Update hook_help for Update Manager module

Looks all fine to me.

Let's wait for confirmation from the maintainers about the "Install new theme" link.

jhodgdon’s picture

Status:Needs review» Needs work

Thanks for the patches! There are some more things that need to be fixed in this help text.

a) The links to the online docs are still not following our standard template, and all links to drupal.org should be changed to https.

b) We also need to think generally about link text accessibility in this help text. Link text should tell someone what page they are linking to. So for instance, we could expand the link to the available updates report so that "report of available updates" is the link text, and that would give people more information about the page. This is important because people using screen readers often navigate a page by jumping from link to link, and the screen reader reads the link text and/or link title attribute. If the link text is cryptic, they have to try to back up and read the sentence to figure out what the link is.

Another example: there's a link whose text is just "cron". That link probably needs a title attribute to tell people where they'll go if they click it.

An example of good link text is "Update Manager settings", which tells you it is going to the update manager settings page.

c) We need to make sure what is in the help matches what you see in the Drupal UI. For instance, the Modules and Themes pages are actually called Extend and Appearance, so that is how the help text should refer to them.

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new6.33 KB
PASSED: [[SimpleTest]]: [MySQL] 59,632 pass(es).
[ View ]

Patch addresses all issues from #7.

I removed the link from cron, as it was only there as an explanation of the term "cron" and I do not think it is necessary to add some phrase like "for more information about cron, consult the Cron documentation"

I'm not so happy with the term "the Extend page" for referring to the modules list

jhodgdon’s picture

Status:Needs review» Postponed

I don't like "Extend page" either, but that is what it is called, so we need to call it that in the help.

Anyway... I think this still needs some work:

a) Technically you cannot actually disable modules from the Extend page any more. All you can do is uninstall them from the Uninstall tab of the Extend page. So that needs to be changed in the help.

Actually though... Isn't it kind of obvious that if you do not want the functionality a module is providing, you should disable/uninstall it? Maybe we don't need this at all?

b) A little nitpick: I think we should say that you can change settings "on" a page, not "at" a page.

c) "report of available updates" -- again, can we make sure the help text mirrors the UI text? This comment still applies all over the help. We want everwhere you link to an admin page or mention an admin page, for the help to use the actual page title. It is confusing if you call it something other than what someone would see in the UI.

d) When I go to the Update page, what I'm actually seeing is the ability to install a new module/theme, not a list of updates as it says in this help.

I think we should actually postpone this issue until the UI of update module is cleaned up. It's a mess right now. See
#2121725: UI badness in update.module (menus, tabs, etc.)
and probably other issues.

InternetDevels’s picture

Issue summary:View changes
Status:Postponed» Needs review
Parent issue:» #1908570: [meta] Update or create hook_help() texts for D8 core modules
StatusFileSize
new2.58 KB
new6.52 KB
PASSED: [[SimpleTest]]: [MySQL] 60,008 pass(es).
[ View ]

@jhodgdon, thanks for recommendation.
a) Added.
b) Done.
c) Renamed to "available updates".
d) Fixed in the https://drupal.org/node/2121725 issue.

jhodgdon’s picture

Status:Needs review» Postponed

We need to postpone this issue until the UI for the Update Manager module is fixed, because there is no way to be sure what the help should say until it is settled.

jhodgdon’s picture

We just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.

Here is the change record: https://drupal.org/node/2250345

This patch will need a reroll for this change.

batigolix’s picture

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

This actual change is covered in the issue #2294129: Switch hook_help() to use RouteMatch instead of Request

I ll try re-doing the changes included in the path from #10 without attempting a re-roll.

batigolix’s picture

Status:Postponed» Needs review
StatusFileSize
new6.44 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 78,633 pass(es).
[ View ]

This patch incorporates the changes from #10.

I adapted the changes manually without doing a re-roll.

jhodgdon’s picture

Status:Needs review» Postponed

We still need to postpone this issue on #2121725: UI badness in update.module (menus, tabs, etc.), which is attempting to fix the UI of the Update module so it actually makes sense. No point in documenting a UI that doesn't really make sense.

jhodgdon’s picture

Instead of having one critical parent issue I have been asked to change the status of each child issue.

This doesn't seem to be Major or Critical to me, and it still needs to be postponed on that other issue (it is pretty much impossible to document a UI that doesn't make sense).