Lost help for field types from Core/Field

Thinking about the wall of text this is likely to become when moved to a single hook_help implementation, I'm wondering whether it would make sense to delegate the actual content to a static help() method on FieldItemInterface.

Just a thought, haven't actually weighted the pros and cons.

Static methods sounds sane to me. It will allow simple contrib modules that only expose field types - and maybe additionally some formatters and/or widgets to move that there as well. Having to create a module file just for this help would be kind of sad.

The text could be collected and displayed in the field module's field_help() pretty easily, or else in system_help().
But I don't think this should be separated from the parent issue really? The current patch on the parent issue removes existing documentation, which isn't really good.

Those two modules did afaik not have anything useful in their help text, link for example does have relevant information based on what I saw on a quick check.

Right, I don't think a patch should be allowed to remove useful information from the Help system... you could argue that the previous one also removed information, because there was also a field list on the Field help page, automatically generated, which probably doesn't work any more...

I think that is probably true of most fields: the fields themselves do not require any explanation, but the widgets/formatters have config options or you have a choice of several widgets/formatters that requires an explanation.

So... what I think would be useful to do somewhere (either on field_help() or on a report that field_help() links to) -- and I think this is the same as what andypost is suggesting:

a) List all the fields that are currently enabled (core or enabled modules)
- For each field, show the description and any longer help (it might provide this in a new static method on the field class or in the field annotation, probably in the class?)
- For each field, list the formatters and widgets that can be used.

b) List all the formatters that are currently enabled (core or enabled modules)
- For each formatter, show the description and any longer help (it might provide this in a new static method on the field class or in the field annotation, probably in the class?)
- Show the field types it can be used on

c) Same as b for widgets

Does that make sense? If so, where would be the best place to do it?

And I guess since this is all help, I would vote for it being listed directly on the field_help() page in place of the "list of enabled field modules" that is there now, rather than being part of Reports.

One thing about documentation maintainability is that the farther documentation is from code, the less likely it is to be maintained. So in my opinion, the best place to provide documentation about a particular field would be in the field class itself (either in the annotation, if it's short descriptions, or in a method if not).

We're talking here about hook_help() and the information that used to be in hook_help() that is no longer there. Tour is barely used in Core and isn't the same thing at all, and the field list form is also not the same thing.

Exactly. But we need to get it into the hook_help() system. That is the help system we have, and it used to display information about these fields. Now it doesn't. That is a regression that we need to address.

#2351991: Add a config entity for a configurable, topic-based help system would probably provide a solution...

Over on #2354539-2: [meta] Convert help to new config entities I put in a specific suggestion for how the config entities could solve this issue.

The proposal in #20/21 is not going to happen. The issue was reclassified as a feature request and therefore postponed to 8.1.x.

So we have as far as I know no viable proposal here. And we need one. We lost documentation that we had before and this is not really acceptable.

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

At this moment, we have several fields that have completely lost their help, so this is Critical.

Not sure the help text we lost was actually useful?

However #1963340: Change field UI so that adding a field is a separate task just went in (was mentioned in #10).

Some of it was trivial, but not all. There was quite a bit of information on some of the text that was removed.

Namely, some of the fields have quite a bit of configuration and etc. that was documented in those modules' help. This has been lost.

OK. I went back in the time machine to Alpha 8 (the modules had vanished by Alpha 9), vs. now, and looked at what exactly we have already lost here:

a) Email module - that had some help text about displaying email addresses as links and validating email addresses. Fairly minimal. I am not too sad about losing it, because it didn't say much of anything that shouldn't be fairly obvious [added some comments and abbreviated the first line]:

   // Duh. I think people can figure out to use an email field for email addresses from the UI and they now don't need the module.
      $output .= '<p>' . t('The E-mail module allows you to create fields that contain e-mail addresses.  ...

   // This can easily be figured out from Manage Display.
      $output .= '<dt>' . t('Displaying e-mail addresses as links') . '</dt>';
      $output .= '<dd>' . t('E-mail addresses can be displayed as <em>plain text</em> or as <em>links</em> by choosing the appropriate display format.') . '</dd>';

   // This is maybe not obvious, but on the other hand I think most people would expect
   //  a special Email field to do some validation?
      $output .= '<dt>' . t('Validating E-mail addresses') . '</dt>';
      $output .= '<dd>' . t('E-mail addresses are validated when the content is saved.') . '</dd>';
      $output .= '</dl>';

b) Number module - that had some help that described what the different types of number fields mean:

      $output .= '<dd>' . t('When you add a number field you can choose from three types: <em>decimal</em>, <em>float</em>, or <em>integer</em>. The <em>decimal</em> number field type allows users to enter exact decimal values. The <em>float</em> number field type allows users to enter approximate decimal values. The <em>integer</em> number field type allows users to enter whole numbers, such as years (for example, 2012) or values (for example, 1, 2, 5, 305). It does not allow decimals.') . '</dd>';
 

This actually seems like useful information that isn't explained elsewhere that we should not lose.

So those are the only two that have been removed so far. On #2202925: Move simple field types into Core/Field, there is a proposal to remove link, options, telephone, and text modules. So let's see what help we'd lose there:

c) Link module - There's quite a bit of useful information there about formatting them.

d) Options module - Has quite a bit of useful information about what they mean and about setting them up.

e) Telephone module - The information about displaying telephone numbers as links is actually relevant and useful, and is important for documenting accessibility (accessibility features need to be documented to satisfy ACAG guidelines).

f) Text module - Has quite a bit of relevant and useful information about choosing between the text field types, and their settings and formatters, as well as editors and text formats.

So... It does seem to me that this is a real problem that we still need to solve. There is quite a bit of relevant and useful documentation that would be lost if we get rid of these additional 4 modules, and we've already gotten rid of some useful information in the Number module help.

So far I have not seen a viable proposal, but we do need to do something...

My feeling is that since we only have hook_help() available to us in Core for providing help, and this is one page per module, we need to get this help displayed on the Field module help page, which is now the central page (linked from other modules) that tells about entities and fields (at least, it will be once #2091321: Update hook_help for Field and Field UI module gets in), and also it already is listing the available Field, Widget, and Formatter modules to link to their help. If we'd gotten in #2351991: Add a config entity for a configurable, topic-based help system we'd have the opportunity to write topics that way, but we didn't, so I think the only logical place to display this help is on the Field help page.

So. The easiest way to get this into the Field help page would be to add the text as new sections directly in field.module field_help(). That is one option.

The second way to get this into the Field help page would be to add some kind of a method to the Field (and possibly Formatter and Widget) interfaces/classes that would provide help text, and to iterate over core Fields (Formatters, Widgets too?) and display the help as part of the PHP code of field_help().

As we're already in beta and trying to get Drupal 8.0 out the door, I would vote for the simplest option at this point, which would be:

a) Right now: patch field_help() to restore the lost information for the numeric fields. We'll need to add a new section to that help page titled something like "Information on Core fields", and explain that this section contains help on some specific fields that are provided by Drupal Core without additional modules being enabled. Would be nice to wait on #2091321: Update hook_help for Field and Field UI module or add it to that patch, since that patch also changes field_help().

b) As more Core field modules are eliminated on the parent issue, take the useful parts of their hook_help() and add it to that same section.

What does everyone think about this proposal? I'd be glad to make a patch for (a) and to help with (b) as we go...

Advantages of this proposal:
- Pretty simple to do, code-wise
- Doesn't require any API changes or additions
- Help will definitely get on the right page (Field help page)

Disadvantages:
- The help for these fields is far removed from their code (modules/field/field.module vs. core/lib/Drupal/Core/Field/Plugin)

I like the a)/b) proposal, that'd make this very straightforward to resolve.

We could open a separate task to look at adding descriptions to field types/formatters/widgets somewhere that could be re-used for help/Field UI - would be an API addition so can happen any time.

OK. Having the Core maintainer for Docs and one branch maintainer agreeing is good. Anyone else object?

If/when we're agreed, I can either wait for #2091321: Update hook_help for Field and Field UI module and then make a patch here for (a), or add the Number information to that patch. Or we could do both (a) and (b) on #2202925: Move simple field types into Core/Field.

So, I'll give this idea a few days to simmer, meanwhile officially making it Proposed in the issue summary (which was otherwise rather blank)... Anyway, the next few days are family/holiday time. May make some Drupal contribution time next week; might be after the 1st. Happy holidays!

It's technically possible to have the field module disabled but still use the number field types, so somehow having that information there is not entirely right. However, in almost every scenario of a D8 site, field module will probably be enabled so I guess we can just go ahead.

I think that it's unlikely that someone having the knowledge of how to set up entity fields, form modes, and display modes without Field/Field UI would need the guidance in the help (which is about how to choose between the numeric field types, and for the other fields, mostly about formatters and widgets). Seems like an edge case.

I'm definitely in favor of having good descriptions on the field classes that actually reflect what the fields do, but help is really oriented towards more novice users.

Adding this to field module sounds good to me as well.

@catch: so far I only see you and me agreeing. Should I go ahead?

Yes I think so. Personally I don't think this particular help is critical to have (it's not same as an entire module missing a hook_help() - since that explains the existence of the module at all), but having the information in field_help() resolves the missing bit, and we can look at improvements in other issues.

OK. I was going to make a patch for this, but the help for the Field module has a patch waiting for review (which I also wrote) on #2091321: Update hook_help for Field and Field UI module.

Taking care of this issue will be a lot easier with the updated help information that is in this patch. Therefore I think we should postpone this issue until that one has been taken care of. Accordingly I am going over right now to up the priority of that other issue.

Actually that other issue is already Major and probably since right now the only help that is missing is Number, we can just demote this one to Major.

Ok, that seems to be fixed now.

OK. So the plan here is that we need to add a section to the Field module hook_help about the core fields, and for now just add information on the Number field there.

Here's a patch, and a screen shot of the resulting Field module help page (I skipped the About section at the top, which doesn't change).

It's only partially related, but: @jodgdon commented in #2202925: Move simple field types into Core/Field which field types have useful documentation. That's correct, but each of them also is 90% copy & paste text about how to add fields and so on.

We have a completely new field UI now, where we have a lot more space on the UI where you select the field type when creating a new field, because it is a separate page now. What about using that to show a short description of what a specific field type does.

Right, 90% of it can be dropped. However there were a few useful bits in the pages I mentioned, so all we need to do is to add those notes like I did in this patch.

If you want to do something more extensive like have help on the field add pages, I'm in favor of it. But at least for now let's not lose the information that we once had in the hook_help().

Can we get this patch reviewed?

Sure, I'll open a new issue to discuss that.

Patch itself looks fine to me, what about making three separate list items for integer/float/decimal? That might be faster to scan/read and it reflects the field type selection. Which might also change into opt-groups, so not sure how exactly it should look (Number (integer) vs. nested lists).

Note that Number is not actually the only field type provided by core. Core also provides:
- The Text (plain) and Text (long, plain) (or something like that..) field types, replacing the format option on text fields in 7.x.
- Email
- Boolean

I don't know if they had useful help before, but we should probably include them here?

Regarding those other fields, I surveyed them in comment #27 and in my opinion, their help didn't have anything useful enough to include here. As you noted above, most of those modules' help was mostly the generic "See the Field and Field UI help for generic information on fields".

Regarding the number help, I made it a single bullet because I thought that the important message was about how to choose between the different types of number fields, so I thought it belonged together in one paragraph. If we split it up then it becomes on equal footing with the other field help that might get added later, and then someone might get the bright idea of alphabetizing the whole list and those could get split up... so I'd kind of prefer to leave them together in one paragraph.

??

As another note, we don't have to have information on all the core fields. That is why the header text in this area says something like "Core provides a number of fields. Here are notes on a few."

Ok, if you think that the others don't need documentation and this is enough to get rid of a major then that's fine with me.

Requesting https.php with a legitimate simpletest User-Agent returns OK.	Browser	SimpleTestBrowserTest.php	105	Drupal\simpletest\Tests\SimpleTestBrowserTest->testUserAgentValidation()	

This issue addresses a major bug and is allowed per https://www.drupal.org/core/beta-changes. Committed 7ce6154 and pushed to 8.0.x. Thanks!