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

#7 field-ui-help-text-2091321-7.patch12.22 KBifrik
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 66,969 pass(es).
[ View ]


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)?

Issue summary:View changes
Status:Active» Needs review
new12.22 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 66,969 pass(es).
[ View ]

Here's a first draft to re-do this.
I've mainly split the Uses into field settings, form display and display, plus knowing where to find out where all those fields are used.
The field settings are a bit complex because we have both the general field settings and the specific ones, and they are referred to in the same way.
Can somebody have a look at it to see whether that's a suitable way to go? Then I can finetune to wording afterwards.

Status:Needs review» Needs work

Hooray! I was hoping someone would write this sometime soon.

So, yes! I think this is a good approach. There are a few typos, which I didn't review carefully, since I think you are planning to fine tune. Two small typographical notes:
- When making lists like "a, b, or c" or "a, b, and c", we always want a comma after "b".
- Also I noticed an a herf tag instead of href. Near the end, in the "Listing" section.

Regarding the two types of settings... hm.... Yeah, the UI is bad. :( So, in the programming end of things, these are called "field settings" and "instance settings", and actually "instance settings" shows if you hover over the Edit link in the UI. So I think we can call them that in the help.

One other note... You cannot actually reuse fields across different entity types, only across sub-types or whatever we are calling them (for instance, fields you created for one content type can be used for another content type, but not for custom blocks or taxonomy terms).

I just checked the entity help and we describe them this way:

This information is collectively know as "entities", which are grouped into "entity types" (such as the main site content, comments, custom blocks, taxonomy terms, user accounts, and views configuration). Some entity types are further grouped into sub-types (for example, you could have article and page content types within the main site content entity type, and tag and category vocabularies within the taxonomy term entity type); other entity types, such as user accounts, do not have sub-types.

So we should be sure to use the same terminology in this help.