Update hook_help for Field and Field UI module

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. :)

So...

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

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

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.

Thanks!

We just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.

Here is the change record: https://drupal.org/node/2250345

This patch will need a reroll for this change.

Straight re-roll, therefore no interdiff.

Whoops, Issue Status.

Whoops, there was unresolved feedback... back to Needs Work. :P

Did changes as mentioned in #9 and also fixed some broken links in this patch. And also attached the screenshot of Field UI help page.

Please review.

Fixed field help page URL.

This text is still not accurate. You do not attach fields to an *entity*, you attach them to a sub-type. See comment #8 above.

Once we get the text being accurate, I will review the details more (typographical, grammar, etc.), but right now this is a major problem and the text needs to be rewritten completely.

I'm not thrilled with the term "entity sub-type" but since that's the wording we're using I went through and updated everything to match.

I added the Oxford comma where I noticed it lacking, and made various other typo cleanups. Several places used the verb "clicking" (as in a link), and I changed that to "using" since not everyone will be clicking -- if there's a better standard term for that, let me know.

There's a lot of "you can do x, and you can do y, and you can also do z" that makes it seem verbose. There's also a lot of "the settings include, for example, x, y, and z" because a lot of settings are dependent on what type of field it is. Additional work could be done to try to pare that down.

Looking much much much better, thanks! A few things I think could be improved:

a) Let's capitalize the content type and vocabulary names in the About:
... such as article or page content types, or tag or category taxonomy terms. ...
==>
... such as Article or Page content types...

This also needs to be done elsewhere in the help where these content types are mentioned, such as in the field reuse section.

b) In "Creating a field":
"Entity sub-types include content types, taxonomy terms, and user profile accounts."
Hm.... Taxonomy terms are actually entity objects, the same way nodes are entity objects. The sub-type is the taxonomy *vocabulary*, the same way the content type is the sub-type for nodes. This also needs to be checked in the other sections of the page.

c) Next sentence:
" You can add new fields on the Manage fields page of an entity. "
No. It's on the entity sub-type, not the entity.

d) Same section:
" When you add a Label text, a machine name is automatically generated,"
Text is not countable, so you do not add "a text". Just take out the word "a", so it becomes "When you add Label text...".

d) The settings for a field are described twice: once in the Creating a field section, and then again in the Configuring section just below. This is redundant. Let's just do it once. Also, the information is confusing, because in Creating it says once you've created the field you cannot change the settings, and then in Configuring it says you can click Edit. Which is correct?

e) Configuring a field in a form section:
"On the Manage form display page of your entity,"
entity sub-type again! :)

f) Same section:
"allow you to configure the field further".
No, you are configuring the *widget* not the field. We need to be careful to be clear about this.

g) Same section:
"you can configure how each field is displayed on content creation pages"
I don't think I would say "displayed" here. I think I would say "edited".

h) In general... There is different usage of the word "field" throughout this help and it is very confusing. Sometimes it means "a field that is attached to an entity sub-type" and sometimes it means "a place to configure some kind of a setting for the field, widget, or formatter". I think we need to make this distinction clear.

So what I would propose is: In the About, we should add something like:

Note that throughout this topic, when referring to a Field in this sense, the word Field will be capitalized to distinguish from other uses of the same word.

Then we would make sure to capitalize the word "Field" when it refers to a Field module Field, and leave it lower-case for other uses. Either that or we should only use the word "field" to refer to a field-module Field and find another word for the other uses. ???

i) Widget section again:
"one or several widgets are available that allow you to configure the field further"
Um... maybe "one or several widgets are available, and most widgets have configuration options" ?

j) Display section:
"in a teaser or as a search result".
Do not use search result as an example here! That will confuse people a lot, because it doesn't really mean "Display this field as configured when you are building the search result page", it actually means "Render this field as specified, and use it to extract a snippet for the search result page". So I think it would be better to say "in a teaser or full page view" for the examples.

k) same section:
"one or several formats are available that allow you to configure the display of the field further"
As in Widget section, I think this would be clearer as "one or several formatters are available, and most formatters have configuration options". [Note: I also think we should call them "formatters" not "formats"]

l) same section:
"You exclude a field from a specific display, by choosing..."
I think the word "can" is missing?

m) Reusing section:
"(If no fields are available that could be re-used, this list is not displayed.) "
Verb tense: could => can

n) Listing section:
"all fields are listed with name, type and linked to the entity sub-type with which they are used"
Um. This seems a bit awkward grammatically... How about:
each field is listed with its label, field type, and a link to the entity sub-types where it is used

...actually, we should check what happens in this list if you reuse a field. Do you get one entry or multiple?

Anyway... This is all fairly minor except we need to figure out what to do about (h). Looking really good!

This issue #2041819: Update hook_help and menu entries for Entity module to describe display modes contains a patch that tries to change the field_ui module hook_help.

I proposed to close that issue and continue the work here.

These are the changes we would like to include in field_ui hook_help (coming from : #2041819: Update hook_help and menu entries for Entity module to describe display modes):

a) add a section that explains entities:

Entities

The website's content and configuration 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.

Content entity types store most of their text, file, and other information in field

Configuration entity types are used to store configuration information for your site, such as individual views in the Views module, and settings for your main site content types. Configuration stored in this way can be exported, imported, and managed using the Configuration Manager module. See the Configuration Manager module help page for more information.

b) add how to use display modes:

Managing view modes
Each content entity can have various "modes" for viewing. For instance, a content item could be viewed in full content mode on its own page, teaser mode in a list, or RSS mode in a feed. You can create, edit the names of, and delete view modes on the View modes page. Once a view mode has been set up, you can choose and format fields for the view mode within each entity sub-type on the Manage display page.
Managing form modes
Each content entity can have various editing forms appropriate for different situations, which are known as "form modes". For instance, you might want to define a quick editing mode that allows users to edit the most important fields, and a full editing mode that gives access to all the fields. You can create, edit the names of, and delete form modes on the Manage custom form modes page. Once a form mode has been set up, you can choose which fields are available on that form within each entity sub-type on the Manage form display page. 

c) add description to field ui pages:

+
+    case 'entity.display_mode':
+      return '<p>' . t('Display modes include view modes (used to view content differently for different situations) and form modes (used to make different entity editing forms for different situations).') . '</p>';
+
+    // View modes.
+    case 'entity.view_mode_list':
+      return '<p>' . t('Use view modes to display content differently for different situations; for example, \'Full content\' or \'Teaser\'.') . '</p>';
+
+    // Form modes.
+    case 'entity.form_mode_list':
+      return '<p>' . t('Use form modes to edit content differently for different situations; for example, \'User edit\' or \'User register\'.') . '</p>';
   }

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

This issue is Major. We are missing some very important help.

Phew! I decided it was time to move this issue towards completion.

So I did the following:

a) Rewrote most of the Field module help, including the terminology about entities and fields that was previously in the Entity help (there is no more entity module). I decided the best thing to do was to add a Terminology section after About. I think we did that on at least one other help page but I have no idea which one. Anyway, it seemed like a good idea, because it wasn't an "About this module" or a "Uses" but we needed the information. I also added formatters to the list of modules; not sure why they were not included before.

b) Throughout other core module help, replaced links that had gone to the Entity module help with links to the new Field module help (these were links like "For background on entities, see the Entity module help page", and this info is now on the Field help page). I think I found all the links.

c) Rewrote the Field UI module help, and reorganized the Uses section. I think it's pretty clear and pretty compact now, but presents all the necessary information. I added sections on how to manage view modes and form modes, which had been in the Entity help previously (it is now part of Field UI module).

So... Help pages that should be looked at to make sure they're OK with this patch:
Field
Field UI
Comment
Content Translation
Entity Reference
Responsive Image
RESTful Web Services
User

Given that I changed I am pretty sure every line in the previous patch, I have not made an interdiff file.

#2332687: Lost help for field types from Core/Field is now postponed on this issue. Can someone please review the help?

Reroll.

Committed and pushed to 8.0.x. Thanks!