Views has added places in the $data array where you can identify Advanced help pages that should be shown for that item, and we should think about doing the same for fields and widgets in field and widget info. We lost the field and widget type descriptions when the Manage fields screen was adjusted, and we have so little field documentation already, so maybe there's a way we can use Advanced help to provide more details about fields and widgets in various places in the CCK UI.

I don't know exactly what would fit in where, just flagging this as something to investigate.

Comments

yched’s picture

yched commented

+1 on the idea, of course.
I was not aware of the 'help topic' entry in views data hooks. We definitely should have something similar.

- 'help topic' in hook_field_info()
Shows as a help link at the top of the field settings page
- 'help topic' in hook_widget_info() ?
Shows as a help link in the 'instance settings' section on the field settings page ?
Not sure about this one, the 'instance settings' section mixes widget settings and generic instance settings (help text, default value...)
- For now, we have no specific spot in the UI to put help links for formatters (no formatter settings page...)

I think focusing on hook_field_info() should be enough for a 1st pass.

I was also thinking it would be worth having a 'Field types' help page, which field modules would use as a parent for their 'foo field type' help page. This would have the advantage to those pages to one spot in the CCK help outline. We could then put a link to that page next to the 'field type' selector in the 'add new field' selector on 'Manage screen'.
Of course, this relies on contrib fields to follow that recommendation...

karens’s picture

karens commented

I think it would be worthwhile to figure out a standard place for help. Since this is all new, no one has done anything yet and there's a good chance we can get everyone to do it the same if we set up a standard. If we don't set a standard, they're going to start doing things in different ways and it will be hard to regroup.

I've already started Advanced help for the Date module, but I had to put it into its own section for lack of any place else to put it.

Can a help file use a parent from a different folder? If so, adding some parent locations into the CCK help text makes sense. I haven't tried this so I don't know if/how it works.

karens’s picture

karens commented

And we can create some examples using the Text, Number, Nodereference, and Userreference modules by giving each of them their own help folder to show how other modules should do it, rather than lumping them all together in the Content module folder.

yched’s picture

yched commented

It is possible : I shamefully point to #307787: Let topics have topic from other module as parent...

I completely agree on #2 and #3. Do you have time to start this ? :-) I think we can even start with empty 'To be done' pages.
The important thing is not so much to provide actual help on core fields, that are fairly 'simple' (er...), but, as you point out, to provide example for contrib fields.

karens’s picture

karens commented

I tried this out and ran into a bug in Advanced help. I posted a patch there. With that fix it works.

But this will change translations yet again. Should I wait until we do an official release? Especially since it won't work until Advanced Help gets updated.

yched’s picture

yched commented

I think we should move on with this before releasing, to settle example.
- I guess maybe we can negotiate an early 1.2 release of advanced_help with Earl ?
- translation of advanced help files is not as 'critical' as translations of the UI IMO
- at worst, translation issue doesn't exist if we start with empty 'To be done' pages.

karens’s picture

karens commented

I set this all up and got it working. It turns out you have to have at least one 'local' file for it to work, i.e. you can't have as the only help file a file that has a parent somewhere else, because there is a top-level index that needs something in it.

So I created a top-level 'overview' document that just says this is a CCK field and links to the list of CCK fields.

Since I was doing this, it was easier to go ahead and add some documentation while I went, and since I hardly ever have time or inclination to do documentation, I thought I'd better go ahead and commit it.

I totally agree that the whole 'Advanced help' area can remain untranslated for now, but I wanted to be sure to get some documentation captured while I was in the swing of things.

I also picked up the changes in #324826: Update path: and topic: in documentation (a recent change in Advanced help) and made sure the new files followed that pattern.

The one thing I didn't do was to add any kind of hook to the field_info(). I think we could just call it 'help topic', to be consistent with what Views calls it. Even if we don't use it anywhere yet, we should probably set the standard for where it will go and what it will look like. But that is still a TODO, so I'm leaving this open.

yched’s picture

yched commented

w00t ! way cool !

yched’s picture

yched commented

Thx to #326765: Error if all module's topics are childs of other modules, modules can opt-out of the general advanced help index. I did that for field modules and removed the 'overview.html' files.

yched’s picture

yched commented

I added a link to the 'field types' adv_help page in the description of the 'Add new field / pick field type' select on 'Manage fileds'