Implement hook_help() for views.module

An initial implementation of hook_help(). Good descriptions for use cases needed.

needs review to send to the testbot

related #1876906: Implement hook_help() for views_ui.module

This issue is for the help for the views module (not the views ui module). So I think it needs to be different.

Probably, both this patch and the one from the ui help issue should be applied and tested to see what the help looks like. I think they are separate pages, but they are different modules and so should not have the same help. It should be specific to the module they are.

So I think here, the function name should probably be like in comment #1.

------
this doc about help will be helpful for whoever does a review: http://drupal.org/node/632280

Is that text from the d7 contrib views module?

+++ b/core/modules/views/views.moduleundefined
@@ -16,6 +16,22 @@
+      $output .= '<p>' . t('Views module provides a flexible method to control how lists of posts are retrieved and presented.') . '</p>';

it's more than just list posts... so lets say in general something about listing, retrieving and presenting, and then use posts as an example.

+++ b/core/modules/views/views.moduleundefined
@@ -16,6 +16,22 @@
+      $output .= '<p>' . t('If you are new to Views, try the Simple Views module which can create some often used Views for you, this might save you some time.') . '</p>';

I think if we want to link to the simple views module, a link would be helpful. whoa, it's 6.x http://drupal.org/project/simpleviews So lets not mention that.

But perhaps we should only mention other modules that come with core?

We should compare with what some other hook_help does for other modules in core.

---
In general, this patch is great, because it puts some text and the right sections in the help.
Now we can have some more people suggest what the text should say.

With all the UX work that has gone into Views I think it would be sad to reference simpleviews. I definitely miss the fact, though, that views module does nothing (in the eyes of a site builder) on its own, and that you probably want to enable views UI.

I also agree :D But does anyone know what should be good help text then?

What about mentioning first tour module and then the other default views, which would give them a great start.

Looking at what the help text standard has for an example: http://drupal.org/node/632280
Here is a rough draft (some sample text is left from the help text standard sample):

<h3>About</h3>
<p>Views modules are used to make lists and customize their display, for example sorting. The Views module is the API. To get a user interface, enable View UI.</p>

<h3>Uses</h3>
<dl>
<dt>Front page list of content</dt>
<dd>To configure a particular content type for translation, visit the <a href="admin/structure/types">Content types</a> page, and click the <em>edit</em> link for the content type. In the <em>Publishing options</em> section, select <em>Enabled, with translation</em> under <em>Multilingual support</em>.</dd>

<dt>Changing default views</dt>
<dd>Use the <em>Language</em> drop down to select the appropriate language when creating or editing content.</dd>

<dt>Using custom views</dt>
<dd>Creating custom views can expand both user facing functionality, for example: 10 top posting users profile pictures, and administrative functionality, for example: content of type Article from the last 30 days that is unpublished.</dd>

<dt>Exporting and Importing</dt>
<dd>Users with the <em>translate content</em> permission can translate content, if the content type has been configured to allow translations. To translate content, select the <em>Translation</em> tab when viewing the content, select the language for which you wish to provide content, and then enter the content.</dd>

<dt>Expanding Views functionality</dt>
<dd>Contributed projects ...</dd>

I wonder if we could look at some of the top 3 views videos or Drupal books and see how they describe views to get inspiration.

The Views module and Views UI both need to have their own hook_help text. See the core Field and Field UI modules for an example.

I have some ideas on what these could say... Note: I am not sure what the Usability folks have decided we are using as a generic term for "entities" in the user interface? substitute that for [entities] in the text below.

So... I think probably the Views module should probably not have a "Uses" section, but just an "About":

-----
About
The Views module provides a back end for making sortable and filterable listings of [entities], known as "views". Examples:
- A list of the titles of the most recent blog articles
- A sortable table of members' names and addresses
- A filterable administration page with bulk operations on taxonomy terms

The Views module has no user interface itself. In order to create and modify views in the administrative user interface, you will need to enable either the Views UI module or a contributed module that provides a user interface for Views.
-----

And then the Views UI help would say something like this:
---
About
The Views UI module provides an advanced user interface for the back-end (link to help)Views module(end link), which allows you to create and modify "views", which are sortable and filterable listings of [entities].

Uses
(this would list things like creating a new view, and overriding a view provided by a module)
---

Thoughts?

Views modules are used to make lists and customize their display, for example sorting. The Views module is the API. To get a user interface, enable View UI.

While code-wise being mostly correct, this would be pretty much misleading, at least to the slightly below average admin.
It suggests that it made almost no sense to install Views without Views UI, because without Views UI, your views wouldn't have any user interface at all. It's up the definition whether technically speaking that's correct or not. From the user's perspective, it certainly isn't. Drupal core renders views fine even without Views UI. It even allows for sorting and filtering and what now.
Rather only the administration & configuration interface is added by Views UI.

See also #2037783: Make module description for Views reflect its importance with most of the arguments applying here, too. We might even want to figure out the right description first, and extend it to a help text later, but this is not necessary.

OK, well then I think #15 just needs to be amended for Views to take out the sentence "The Views module has no user interface itself." leaving just this at the end:

In order to create and modify views in the administrative user interface, you will need to enable either the Views UI module or a contributed module that provides a user interface for Views.

And maybe the About section should add:

Many Drupal Core administrative pages are enhanced with sorting and filtering if you enable the Views module.

Changes in #18 would be a step forward, but not enough.

#15 is only a very rough draft (YesCT didn't state more) that still contains sample text, and with the rest needing work.
Custom views can only be created with the Views UI, so that paragraph is misleading. Plus "sorting" is not "customizing", and the term "customizing" needs to be avoided in this context.

Also, the administrative pages are not only enhanced with sorting and filtering - without Views, the whole listings disappear!
It is extremely important to make sure we're not misleading anyone, because otherwise this could become one of the greatest D8 WTFs.
I might find some time later coming up with a new proposal that builds upon what we already have here, but I can't promise atm.

That last statement is, I believe, not accurate. It is my understanding that there are at least fallback admin screens for core that work without Views. Someone told me that recently anyway.

I'm confused about which paragraph in #15 you think is misleading? I don't see anything about "customizing" anywhere in #15 or #18? Maybe you are confusing it with #14, which I think has some problems that were addressed in #15/#18?

And definitely feel free to propose better wording.

Here's a revised version of the help text for review. I got some details from the handbook pages, which helped with terminology and some of the issues mentioned above.
Needed:
-Please comment with reviews, suggestions, additions etc, I'll modify and create a patch.
-Could someone point me in the right direction for the translation stuff ($output= . t() etc), in case I don't find it on my own? thank you!

<h3>About</h3>
<p>The Views module provides a back end to fetch content from the database and present it to the user as lists, posts, galleries, tables, maps, graphs, menu items, blocks, reports, forum posts etc. The resulting displays are known generally as "views." The Views module is enabled by default and adds the ability to sort and filter content to many administrative pages.</p>
<p>In order to create and modify your own views using the administration and configuration user interface, you will need to enable either the Views UI module in core or a contributed module that provides a user interface for Views.</p>
<p>More information can be found in the <a href="https://drupal.org/documentation/modules/views">online handbook pages for Views</a>.</p>

<h3>Uses</h3>
<dl>
<dt>Display list of recent content</dt>
<dd>Use Views to create a block with a list of the titles of the most recent blog articles, selected using content type or taxonomy terms and sorted by date. From the admin/structure/views page, use: "Add New View."</dd>

<dt>Changing default views</dt>
<dd>Use the Views administration page to edit default views for standard pages such as Content, Files, People, and the Frontpage. Details that can be adjusted include filter criteria, sort criteria, header and footer.</dd>

<dt>Using custom views</dt>
<dd>Creating custom views can expand both user facing functionality, for example: 10 top posting users profile pictures, and administrative functionality, for example: content of type Article from the last 30 days that is unpublished.</dd>

<dt>Exporting and Importing</dt>
<dd>Views can also be exported and imported across sites. [not sure what @YesCT had in mind here]</dd>

<dt>Expanding Views functionality</dt>
<dd>Contributed projects that support the Views module can be found <a href="https://drupal.org/node/264141">here in the online handbook</a>.</dd>
</dl>

Thanks! This is a great start. A few comments:

a) The first proposed paragraph of About says that Views can make "posts"... huh? And graphs, really? I don't think so, not without a contributed module. Stick to what Views Core can actually do, please.

b) We have standards for how to do help: http://drupal.org/node/632280 They are not being followed here completely.

c) The Uses section first item seems to be a very specific example of a view, not a general "use" of the module.

d) The third item should probably be "Creating custom views". Its text needs to be rewritten though, since it's kind of garbled and run-on. Just stick to what it means to create a custom view, not listing a bunch of examples.

e) "here in the online handbook" is not a good link text, for accessibility. Also we don't refer to it as the "handbook" any more -- it's the online documentation. And any page linked to should be checked to see if it is appropriate to Drupal 8, and given a page alias so the URL is not "node/122333333" .

Created initial patch.
Regarding comments from #22:
a) fixed
b) fixed? or, please, be more specific about which standarts are missed
c) fixed
d) fixed, about page link - https://drupal.org/node/264141 I dont see any alias for it.

Looking better, thanks! A few things to address:

In the About:
a) I don't see how the Views module can present data as "posts"? It's always a list, grid, table, etc. I also don't see how a block is in the same category as a list or a table -- one is the way items are formatted (table, list, grid, etc.), and the other is where it is output to (page, block, etc.). Maybe this sentence needs a little bit of clarification?

b) ... generally as "views." : I think the . should be after the " here?

c) The Views module is enabled by default ... : Doesn't that depend on your install profile? Which install profiles have it enabled by default?

d) More information can be found in the <a <a href="@views">">online handbook pages for Views</a> There are two A tags here, and also this is not the standard way to refer to the online docs. See the help standards referenced above for the standard wording.

e) There should be a link to the Views UI help page when Views UI is mentioned.

In the Uses section:

f) All Uses headings should be -ing verbs.

g) Some of these items still are specific examples rather than general help.

h) Some of these items are only possible with the Views UI module, so they should be described in that help page and not here.

i) I would avoid the use of so many "also" words. Make each item stand on its own.

j) The link text for the last item is "online documentation", but it is a link to a specific page. That is not accessibility-guidelines-compatible link text -- it needs to describe the page being linked to. I also made an alias for that page:
https://drupal.org/documentation/modules/views/add-ons

Thanks for all the comments, @jhodgdon. And thanks @babruix for the new patch.

a) that list of things Views can produce came from the online documentation page for views, which I copy/pasted thinking it would be more accurate than something off the top of my head. Should be fixed now.

b) hm, tricky question, but I see what you're saying and have changed it.

c) how about just taking out the "enabled by default" altogether?

d) fixed the <a> tags and wording, but I don't entirely understand how URLs work here.

e) fixed and reorganized a little so the flow makes more sense.

f) fixed. ing.

g/h/i) fixed? After reading the comments here again, it does seem that Views by itself doesn't need much help text, and that most of this should go on the Views_UI help. So, try this newly reduced version, and sorry for the confusion. Maybe this could use a little more clarification on what exactly Views does on its own?

j) also fixed, but as mentioned in #11, do we really want to reference contrib here?

On quick nitpick about the link tokens. Use ! rather than @

Yeah, I think a Uses item saying something about how Views adds filtering functionality to some core admin pages would be useful. We could take it out of About then (I think it's more of a "use" than a "what is" item anyway). This way at least people would know what might happen if the disable it.

Changed the link tokens to !.
Moved item re: filtering admin pages to Uses.

This is looking great! A few mostly minor comments:

a) Our Drupal content style guidelines require the use of serial commas in lists. Such as:

blue, green, or red
blue, green, and red
not
blue, green or red
blue, green and red

Missing here: "... as a grid, HTML list, table or unformatted list..." and maybe elsewhere (but that is the only one I saw).

b) "...as a grid, HTML list, table or unformatted list..." -- really, these are examples of what Views can do, so this should probably end in "for example" or "etc."?

c) 'The resulting displays are known generally as "views".' ... Should that be put in <em> tags rather than quotes? I am not sure but I kind of think so.

d) The admin item in the Uses section... How about if the heading says "Adding functionality to administrative pages" rather than specifically saying "filtering"? The description could be similarly changed, and "adminstration" is misspelled there.

e) I do not think that the example in that Uses item is actually correct -- is it? I don't see any taxonomy views that would override any taxonomy admin pages. I do see one in the Node module, though. Maybe you could use that as an example (go to admin/content with and without the Views module installed and see what changes)?

a) Got it. The "Oxford comma" issue.
b) I think "etc" works better, and then there's no "or." right?
c) I thought <em>s were used for something else... for referring to parts of the system, such as "then click the edit link" or something like that? I'm not sure either, but quotes would be what I'd use. I've switched to <em>s here, see what you think.
d) Done. Typos, so embarrassing.
e) hm. If I uninstall Views and go to admin/content I get an error and no display at all. Is that what you meant? Should there be a fallback there? I rewrote the Use for this situation, but don't quite understand what's going on here...

Admin/content error with Views uninstalled:

Handy screenshot of views_help() as of this patch:

moops.

I personally like the EM tags better than the quotes, but that is possibly related to the fact that I recently wrote a book for O'Reilly and that was their standard for introducing terminology, so I got used to it. Either way is fine -- I don't think we have a standard, and either way would be clear.

Anyway... The admin/content screen not working without Views is probably a bug but I'm not sure. I'll see if I can find out, or maybe you can find someone in IRC who can answer the question here?

Other than those two details, I think this is looking good!

We do have fallbacks for these admin listings, though uninstall causes issues
in some totally unrelated places in core: #2021779: Decouple shortcuts from menu links

OK, given #33, the help text in there right now is incorrect. What is supposed to happen is that if you disable Views, you get a more limited admin/content.

I waffled a bit on whether to just say "more limited content" or attempt to explain in more detail. "limited to a simple list"?

I think what you have here is fine, thanks!

So this just needs a quick manual test to make sure the formatting is OK and all the links work.

Aside from #38 concerns. #36 Looks good to me!!
@ekl1773 thanks!

RE #38 - "content" is a pretty generic term -- I don't think it's bad to say that Views is for making lists of content. What else would it be fetching that wouldn't fall into the category of "content" -- I don't think we want to use the word "stuff"? :)

RE #38 / damiankliop - do you have a better term to use than "content" in this help text? If not I think we will have to use "content". As far as I know, this question is the only thing preventing this patch from being marked "reviewed and tested"... Thoughts?

36: drupal-views-help-1876904-36.patch queued for re-testing.

It looks like this patch needs a reroll. And the manual testing has been done.

Re-roll

Thanks for the reroll. I think it is ready. Let's see what @jhodgdon thinks about it.

Moving to Jhodgdon for a final look.

Well, #38/@damiankloip pointed out that "content" in the first sentence is not entirely illuminating as to what Views can make lists of.

So I had an idea this morning. Could we say something like this?

(current patch)
The Views module provides a back end to fetch content from the database...
(new idea)
The Views module provides a back end to fetch information from content, user accounts, taxonomy terms, and other entities from the database...

In case people agree this is a good idea, I edited the most recent patch and put this in. Thoughts?

Seems better to me.

This looks pretty good to me. If needed, we can iterate on it later. Committed to 8!