Add hook_help() implementation. [#225440]

The attached patch adds a hook_help() implementation to views.module, displaying a page of views "concept" help at admin/help/views.

I've made this patch against Views HEAD, using the Views 2 interface and concepts as best I could. It is not completely finished -- for instance, the list item for relationships is not complete with explanation nor examples -- but I set it to CNR for feedback. Hopefully, I got this high-level help mostly accurate and have good examples, but if not, I'm happy to change it as necessary.

Comment	File	Size	Author
#8	views-embedded-help-1.patch	4.01 KB	keith.smith
#8
	views-embedded-help-0.patch	4.96 KB	keith.smith

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

KarenS CreditAttribution: KarenS commented 22 February 2008 at 23:16

Status:

Needs review

» Needs work

It would be nice to add hook_help to Views, and this seems general enough that it may still apply to Views 2.

My main question is what kind of user are you aiming at here? I think the hook_help documentation should be pointed at non-developers who would be using the UI to create views, so I would take out references to programming and the fact that developers can do other things with views. Developers most likely will be reading things like the PHP docs rather than the internal help page. Also, I think the internal help doesn't usually talk about installation issues, just how to use it once it's installed, since most users have no access to the installation process and wouldn't know how to do it if they did.

Comment #2

keith.smith CreditAttribution: keith.smith commented 23 February 2008 at 13:12

KarenS: Thanks for the feedback!

By "installation issues", you mean the whole bit about whether the Views UI module is enabled? My idea on that was that this help suffered from the same problem as a similar patch for adding an embedded help page to CCK: there are modules that are optional, and so it doesn't always make sense to talk about them as if they'll always be available.

My target audience, in my head, at least, was the reasonably-savvy administrator (this shows at admin/help, after all) who may be familiar with what Views does, but not all the "ins and outs". I think, based on no evidence, that being able to provide views programmatically without the UI, being able to run stored views without the UI enabled, and being able to hook into Views via the API to make other data available are three overlooked features.

I could well have the wrong target audience expectation. What target audience do you think makes the most use of these help texts? (I don't think developers use them, and end users can't, so I've always targeted the non-"Drupal saturated" administrator.)

Edit: I should also mention that in terms of being "general enough to still apply to Views 2", it is actually the other way around. This text refers to views based on node revisions, users, etc., which AFAIK are Views2-only features. But, it is general enough to still apply to Views 1 if that stuff was removed.

Comment #3

KarenS CreditAttribution: KarenS commented 23 February 2008 at 13:31

There could be lots of people who have access to admin/help who do not have permission to install modules and certainly don't know how to do things programmatically, so my concern is that they would find this confusing. There may be people with access to admin/help who don't even have permission to create views. You don't want to go *that* far down the tree as a target audience, just saying.

I totally agree that there are many things about Views that are overlooked, I'm just not sure this is the right place for info that is only meaningful to programmers.

Anyway, I don't know that my ideas are the *right* ones, I'm just throwing them out as food for thought.

Comment #4

keith.smith CreditAttribution: keith.smith commented 23 February 2008 at 14:58

OK. Those are very good points, and I certainly respect your opinion on this. Both Views and CCK present some challenges in their help text that are not present in, say, Aggregator module; namely, there's so much flexibility and ground to cover. I zeroed in on the API stuff because it let me bring in the fact that Views could be extended (and the interface might not exactly match, or that there may be additional options not mentioned in the help text). The stuff about enabling the Views UI mostly grew out of trying to say that the Views UI was optional -- in fact, that's why I didn't provide any specific help about the UI at all and covered concepts instead. I suppose I could do one paragraph for when Views UI is enabled, and one paragraph for when it isn't, and wrap them in a conditional. Also, AFAIK, all of the help texts in core are written as if the reader has access to all administration pages, which, now that you mention it, could be an issue in some configurations.

I haven't read back through this since yesterday, so I'll take your feedback and a critical eye and make changes (and post a new patch).

Comment #5

merlinofchaos CreditAttribution: merlinofchaos commented 23 February 2008 at 19:24

Ok. I think I'm going to do away with views_ui.module. Initially I had wanted to keep the UI separate, but there isn't very much gain in doing so in D6, because the files are separated into .inc files and the .module itself isn't that much code at this point; mostly it's just a bunch of menu code and some helper utilities that have to be there. So we can eliminate that part.

Second, the reason I never use Drupal's help system is that it's quite limited. I need my help to be inline. And at least a little bit modular, and the help system doesn't really work very well for the modular part.

That said, this is a problem we should solve, but I think we should first solve it without technology. We should analyze the UI we have and figure out the best ways to get help to the user, and then figure out if those are technically feasible with what we have.

As I see it, the biggest places Views 2 needs help right now is:

1) What the hell IS this thing? We need a good introductory help text to describe what Views basically does. It doesn't need to be long.
2) Ok, I've hit 'add' on the views screen. Now what?
3) What does 'display' mean?
4) What is a relationship? Filter? Sort criteria? Etc.

I care very little if this is hooked into Drupal's default help system. If it is, great. If not -- we're not losing much. The paths to actually get to the help are so few that I find it mostly useless to exactly the people who need it.

Anyone have any good suggestions here?

Comment #6

keith.smith CreditAttribution: keith.smith commented 23 February 2008 at 20:07

The patch here (in the original post) has text that can easily be adapted for the needs #1, and #4. I'll take a look at #2 and #3 to see what can be done there, as well as revise the patch here in light of your and KarenS's insightful comments.

Thanks for the comments regarding the future of the Views UI. I'll take that section out, which will free up some much needed space to put some other things in (plus make things a bit more clear).

I share your frustrations about the existing help system, and no -- I don't use the built-in help text all that much myself. It's essentially free, though, which is why I started here. In my mind, ironing out an acceptable help page at admin/help is just a means to an end, that goal being the entire Views 2 interface having better inline help. Working out the terms and concepts -- so that we can then use them consistently -- is what I was after with this patch. As we all know, the information at admin/help, though I'd like to think it increasing in usefulness, is by no means a documentation panacea.

Comment #7

moshe weitzman CreditAttribution: moshe weitzman commented 23 February 2008 at 20:55

I don't much like folding views ui into the views module. we have had some success with disabling views ui in production and instead rolling out default views. this discourages tinkering on the live site. i feel like this is a step backwards. there are more reasons to separate these parts than just saving the load of some code.

Comment #8

keith.smith CreditAttribution: keith.smith commented 23 February 2008 at 21:10

File	Size
views-embedded-help-1.patch	4.01 KB

Attached is a new version that:
- removes the references to the Views API and in general makes this less technical
- adds in the concept of a display
- removes the mention of the Views UI

Known issues:
- need to find good example and description for the "relationship" concept
- if these things ("fields", "sort criteria", "arguments", etc.) are 'concepts', perhaps a display, an override, and possibly others should be included. It took me a bit of playing before I "got" how the overrides were working (say, to create two page displays with different fields).