This issue is part of the task to update the hook_help texts of the Drupal 8 modules:#1908570: [meta] Update or create hook_help() texts for D8 core modules
- review / write the hook_help text according to help guidelines
This help text is way out of date and essential for many other help text because they (will) refer to this for further information.
Some of the to-do's:
- introduce entities (current text tries to avoid that term by describing them all)
- explain form display management
- change url()
Probably the intro to Entities should instead be a reference to the Entity module help, which should be explaining them?
There is a suggestion for what to put in this help text on#2030569-23: [policy] Decide how to refer to "entities" and "bundles" in D8 UI
Although... this suggestion is a bit out of date, since we now want to put an introduction to entities in the Entity module instead and link there.
All of the specific field modules are now expecting something like this to be in the Field UI module help, so we'd better do something like this. :)
We now have a bunch of modules' hook_help() that is referring to this help page. They are expecting the following things to be described (and they should go into "Uses"):
- How to create and manage fields
- The Manage display page for each entity sub-type
- The Manage form page for each entity sub-type
For examples of how we are referring to these, see the Telephone module help (which is in Core now), and the Entity module help (which is in progress on this issue: #2091403: Create hook_help for Entity module). Also, we need to coordinate this with the Field module help -- the idea is that the Field module help will describe what fields are and refer to the Field UI help to describe how to manage them. That issue is #2091319: Update hook_help for Field module.
So I suggest that we have a short "About" section that basically says the module is for managing fields on entities and their display, and refers to the Field module help for an explanation of fields, and the Entity module help for an explanation of entities.
And then we'll need to make sure we have Uses bullet points for "Managing field display" and "Managing fields on forms", which I think are missing from the existing Field UI help. I think the help that is there about defining fields is probably fine -- it definitely seems comprehensive -- but it needs to be reviewed for accuracy in Drupal 8 (e.g., some of the names of pages and labels within pages might have changed).
I'm working on this.
Shouldn't a lot of the text for the Field UI be removed... just a bit too long, not really helpful and wanders into the Field help text territory...
Also maybe there should be help on each of the tabs for managing fields, managing form, managing display (/admin/structure/types/manage/%/fields, /admin/structure/types/manage/%/form-display, /admin/structure/types/manage/%/display)?
Drupal is a registered trademark of Dries Buytaert.