Help File Fixup: Help module

A couple of comments on this patch:
a)

+      $output = '';
+      $output = '<h3>' . t('About') . '</h3>';

Second line should either have .= or the first line should be omitted.

b) "context sensitive help" should be "context-sensitive help"

c) "is annotated with user-contributed comments and serves as..." needs a comma before the and. See http://drupal.org/about/authoring

Formatting looks good.

Just doing a review of the text. 'more' appears close by 2 times. Moving it to the sentence focusing on what online handbooks are.

Before:

After: (just a small change... I wanted to change the epic sentence about online handbooks, but might be best to emphasize this).

Me too.

capitalized H for consistency with other help texts that have been committed. re-RTBC.

Still looks good to me too.

Actually
The standard for capitalization is not being followed. See http://drupal.org/node/632280 -- should start with "The foo module" not "The Foo module" according to standard.

Standard for capitalization was changed, see http://drupal.org/node/537828#comment-2303764 and http://drupal.org/node/632280 -- we are now saying the name of the module should be capitalized. Sorry for the inconvenience but we need a new patch...

I would have suggested going back to the patch in #8, but that is missing one of the capitalizations on the module name too.

OK rerolled but I made the 'handbook' in the 3rd sentence plural and so had to change the grammar. Also added cap to other existing lowercase module.

cleaned up a bunch of the language, and made that final About sentence match the others.

Looks good, let's get this one in!

Hm. One thing that's not quite right. Help does indeed provide context-sensitive help: that's what you see when you go to a page like admin/config/modules and see text at the top explaining how it works. But that is not the same thing as admin/help/X which is not context-sensitive at all, and is instead a... "reference"? Hm. Something.

So we need to re-title "Context-sensitive help" to something else, and add a new entry for Context-sensitive help that basically says Help module will provide little bits of text at the top of certain pages to provide additional assistance.

wow, ok well *that* is a big miss! i've totally updated this one with a more explicit division between the context-sensitive help and the main help pages ("Help reference pages"). i think it can use another review due to the pretty major changes, before it gets RTBC'ed.

Hmmm...

For some reason, the word examples is bothering me in "a brief explanation and examples of uses for each module ...". I don't think we're providing examples per se, but rather explaining what the module can be used for. ???

I'm also not sure if we need the word "further" in " provides further context-sensitive advice " ... Further than what?

And I think I would prefer the wording "displays" rather than "provides", because the modules themselves actually contain the help and the help module is just a mechanism for displaying the help in the ref section and on the admin screens.

By the way, one more thought: Do we talk about "pages" or "screens" in admin? Maybe the help module "displays context-sensitive advice on various administrative screens" would be a better wording?

I sure seem to be more full of questions than answers this morning...

- yes, not really examples.
- further than the main help reference pages
- sure, displays is a bit more precise
- i haven't seen "screens" used anywhere, so i would hate to have to retroactively make that change everywhere there is "page"

someone wanna put these suggestions into a patch? ;-)

no wonder that patch didn't do anything, it's empty :-p wanna reupload that if you still have it?

I would still prefer changing "provides" to "displays" in a few places (such as the DT items), but I can live with this version if others like it.

Rerolled, incorporating comments from #23 and a slight revision of the 'Providing a help reference' section

And how about a screenshot instead of two patches?! ;-)

Looks most excellent. RTBC!

Committed to HEAD! Thanks!