Updated: Comment #0 [no updates yet]

Problem/Motivation

In Help text and possibly elsewhere (but I think mainly in help text), we need to have a standard way to refer to "entities" and "entity bundles" for Drupal 8. This needs to be added to the UI text standards page:
https://drupal.org/node/604342

This is coming up in the effort that is underway to update the hook_help() text. Specifically, in
#2028799: Improve help for link module

For instance, we need to explain in the Link module's hook_help text how to reach the Configure page for a link field. The proposed text is something like this:

Configuring field settings

To configure the settings for a link field, go to the edit page for the [entity] and click the Manage fields link. [...]

We need to know what to put in there for [entity] ... technically really in this case it means "entity bundle" to programmers, but there is no way we want to put that in user-facing help, right? :)

And there may be places in the UI where we want to refer to "entities" as well, but I'm not sure. That may be confined to programmer-facing documentation, in which case we'd want the technical term anyway.

Proposed resolution

batigolix proposed in comment #8 on the Link field help issue to say:

entity (content type, user, taxonomy term, or comment)

This is not quite technically accurate, since really it's "entity bundle" to a programmer, but it does get the point across and defines the word "entity" that is being used there.

Remaining tasks

1. Decide on wording for "entity bundle" and maybe for "entity" as well.
2. Update the standards page https://drupal.org/node/604342
3. Use this in various hook_help text issues and probably elsewhere.

User interface changes

References to entities and bundles in UI would need to be updated, if any.

API changes

None

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

And as a note, I've set this to "major" because it is going to be blocking a number of other issues.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I'm going to add a number of related issues to the summary now that are being postponed until this is decided.

ifrik’s picture

ifrik
she/her
CreditAttribution: ifrik commented

Related is also the question how to refer to [entities] to which fields can be attached e.g. content types, taxonomy terms etc.
The term I hear from developers for this appears mainly to be "fieldable entities".

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

That is a great term for programmers. I am not sure it is a great term for the user interface.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix commented

I propose to use "entities", followed by 2 or 3 examples of entities in Drupal.
For example:

You can add links to entities (content type, user, taxonomy term, et cetera) by adding a Link field

If you do this in the beginning of a document or help text, you can continue using the term "entity".

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix commented
Issue summary: View changes

Add more related issues

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

batigolix: I already added this suggestion to the issue summary, credited to you, when I created the issue. :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

added email help as related issue

ifrik’s picture

ifrik
she/her
CreditAttribution: ifrik commented

Heather James wrote an Introduction to Entities that could be useful for getting the wording right.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

That page that Heather wrote is aimed at developers. There is no way we are going to introduce site builders to the word "bundles".

chris_h’s picture

chris_h CreditAttribution: chris_h commented
Title: [policy] Decide how to refer to "entitites" and "bundles" in D8 UI » [policy] Decide how to refer to "entities" and "bundles" in D8 UI

What are the full list of entities and bundles in D8 core? I would have thought that articles, basic pages, users, taxonomy terms, files and comments would all come under the banner of 'content' for a site builder.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I think that most people would agree that the fields on user accounts are "content", but I doubt that most people would agree that user accounts themselves count solely as "content", since the user name, email address, and password are used primarily for authentication and other system purposes, not for display on the site.

The core entities we have in D8 are... Well, there are a lot:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!EntityInte...

However, many of them are not "content" types of entities, such as "Action", which I think defines system actions you can use in Trigger or Rules.... Hm, I guess we have an interface that is for "content" types of entities:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!ContentEnt...

So assuming that all content-type entities in core do implement this interface, it looks like the list is:
- Nodes
- Comments
- Custom blocks
- Taxonomy terms
- Aggregator feeds
- Aggregator feed items
- Files
- Menu links

To figure out whether an entity accepts fields, you'd have to look at its EntityType plugin annotation header, and see if the 'fieldable' property is set to TRUE or FALSE. Any Entity, regardless of whether or not it implements the "Content" interface, can set this to TRUE. For instance, the User entity is not a ContentEntityInterface, but it does accept fields.

So... Basically the question is still... complicated.

ifrik’s picture

ifrik
she/her
CreditAttribution: ifrik commented

I've also discussed this with Drupalers at the DevDays, and the somebody pointed out that the use of "content" instead of "entity" is already stretching the definition in D7 - and now there are even more entity types in D8.
My feeling is, that we can use the term "entity" because beyond the actual technical term in Drupal, it is simply something that exist. In a help text, we could say an entity (e.g. an article, a user, a taxonomy term etc.)
But I would avoid all mentioning of "entity types" and "entity bundles" - or even entities in plural.
By now I also would leave out the concept of "fieldable" - possibly with the execption of the help text for Fields themselves. (Those site builers that really want to add a telephone number to a menu link, are not really the target audience of the help pages, and get their documentation from other sources anyway.)

So how about a wording like this?

The Link module allows users to add external links to an entity (e.g. to an article, a user, a taxonomy term). (This sentence should work for all modules that define a field for the field module.)

Additional descriptions can be added to the links, and displayed instead of the URL. (Or whatever additional information is relevant for this specific module.)

The link module defines a field for the field module. For more information on how to use fields, see the Field module help page.

For more information on the Link module, see the online documentation.
...
To configure a link field, go to the Manage fields page of the entity to which the link is attached, and click on the Edit link for your link field. For example, if your link is attached to a content type, visit the Content types page.
...
To configure how a link is displayed, go to Manage display page of the entity to which the link is attached and choose the display that you want to change.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I think this is a good plan, in general.

Regarding the exact description:
- Let's avoid "e.g.", since it is (as in your example) usually punctuated incorrectly and often confused with "i.e.". And I don't really like saying that it allows you to add a link to "an article" (which sounds to me like it's one particular article, rather than having a field on all articles).

So, how about this wording, which is a slight variation on one of your examples:

Link module "about" section:
The Link module provides a field that contains an external URL and optional link text; see the (link)Field module help(/link) for more information on fields.

Link module "uses" section on field settings:
The link field has the following field settings (see the (link)Field UI module help(/link) for general information on configuring fields):

And in the display section:
The link field has the following display settings (see the (link)Field UI module help(/link) for general information on configuring field display):

... I'm not sure this is perfect yet; maybe it can be improved? But this way we can avoid talking about entities and how to configure fields on every field module, and centralize the problem to the Field and Field UI module help. Which is better anyway, because if the paths or UI text changes, we would only need to change one set of help text instead of many.

We should also figure out the best wording for the field and field UI help pages, and make sure they cover these concepts (note: I'm not suggesting using this wording, but these are the concepts that need to be covered):
- Entities and which ones are fieldable
- How to add a field to an entity bundle
- How to configure field settings
- How to configure field display
... any thoughts on that?

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix commented

As a reference I checked usage of "entity" in Drupal7.
Currently the word is used in the following UI strings (data from localize.drupal.org):

  1. Missing bundle property on entity of type @entity_type.
  2. For this query an entity type must be specified.
  3. Entity %entity has no base table.
  4. Do not know how to order on @key for @entity_type
  5. Attempt to create field name %name which is reserved by entity type %type.
  6. Attempt to create an instance of field @field_name without an entity type.
  7. Attempt to create an instance of field @field_name on forbidden entity type @entity_type.
  8. The Field module allows custom data fields to be defined for entity types (entities include content items, comments, user accounts, and taxonomy terms). The Field module takes care of storing, loading, editing, and rendering field data. Most users will not interact with the Field module directly, but will instead use the Field UI module user interface. Module developers can use the Field API to make new entity types "fieldable" and thus allow fields to be attached to them. For more information, see the online handbook entry for Field module.
  9. Overview of fields on all entity types.

#8 (from the field_ui hook_help) is interesting because it does what we discuss above: introduce the term and explain it by listing some examples)

LeeHunter’s picture

LeeHunter CreditAttribution: LeeHunter commented

Re #12 I would suggest one change to the about section:

The Link module provides allows you to add a field that contains an external URL and optional link text; see the (link)Field module help(/link) for more information on fields.

ifrik’s picture

ifrik
she/her
CreditAttribution: ifrik commented

I like that!
Leaving out entities in all the field modules and instead putting the effort of explaining it all in the field module means a light clean help text that can also serve as a template for contribe modules.

But I'm not quite sure about the references to to Field and Field UI. Shouldn't both go into the about section. And then "Uses" should only refer to the Field UI page because that's where there is all the info on about how manage them.
The Fields module could then list all the different fields that are available in core, the fact that modules might add more, and where they can be attached to.

So maybe:
About
The Link module allows you to add field that contains an external URL and optional link text; see the (link)Field module help(/link) and the (link)Field UI help(/link) for general information on how to attach and manage fields.
For more information, see the (link)online documentation for the Link module(/link).
Uses
The settings and the display of the link field can be configured separately. See the (link)Field UI help(/link) for more information on how to manage fields and their display.
Configuring field settings
...
Configuring display settings

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Um... Technically, the Link module is providing a field type, and the Field UI module is what allows you to add fields of whatever type to entities. And saying "The Link module allows you to add a field.." without saying what you add the field to seems wrong to me, and I don't really like the wording proposed in #14.

Regarding the wording in #15, it is using "add" in one place and "attach" in another place for the same action. Let's standardize on whatever the Field and Field UI modules use... or actually, let's figure out which one is best and make sure Field and Field UI use that terminology as well. This issue seems like a good place to figure out what term to use for "attaching" or "adding" a field too. :)

Regarding #13, most of that UI text seems to be aimed only at developers. I'm curious where it is being produced, but it doesn't seem all that user-friendly, to say the least! I'm not sure where in the UI text some substitute term for "entity" would appear though... like in the Content Translation module's pages for instance? I think a similar discussion came up there recently, actually.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Priority: Major » Critical

This issue now has several critical issues postponed until this is decided (issues about creating help for modules that do not have hook_help() text), so I am upping the status of this issue to Critical as well.

catch’s picture

catch
he/him
Primary language English
CreditAttribution: catch commented

Should this really block those issues? I feel like we've had this problem at least since Drupal 7, and if there's a standard that could be applied to the new hook_help() as much as the old ones.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
CreditAttribution: webchick commented

I tend to agree. I'd just go with whatever wording for now and then once this issue is resolved, issue "normal" updates to the text.

As far as the issue itself goes, no IMO we don't want to mention anything about "bundles" to site builders, who are the target audience of this text. We should stick to words they'd already see on the screen/previously been exposed to. Therefore, I'd just go with "entity" even though it is technically less accurate.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

My worry is that if we don't decide it now, and resolve all the "create help" issues now, they will never get updated.

ifrik’s picture

ifrik
she/her
CreditAttribution: ifrik commented

Should we have an IRC meeting with some people, go through the options and come up with one that we can use?
That way we have consistency, and even if we later decide to change it later again.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
CreditAttribution: webchick commented

#20: That might be so, but how is inconsistent help text a release-blocking issue?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Priority: Critical » Normal
Status: Active » Needs review

Agreed.

OK, let's for now do this:

- Use the terms "entity items" (for individual objects like nodes, taxonomy terms, and users), "entity types" (for things like Node, Taxonomy Term, and User), and "entity sub-types" for bundles (content types, taxonomy term vocabularies, etc.).
- Try to avoid using the "entity" terms as much as possible. For instance, on individual field type modules, refer to the Field and Field UI modules.

Is that OK for now?

Concrete suggestion for Link module:

About
The Link module allows you to create fields that contain external URLs and optional link text; see the (link)Field module help(/link) and the (link)Field UI help(/link) for general information on fields and how to create and manage them. For more information on the Link field specifically, see the (link)online documentation for the Link module(/link).

Uses
The settings and the display of the link field can be configured separately. See the (link)Field UI help(/link) for more information on how to manage fields and their display. [...]

Concrete suggestion for the Field module:

About:
The Field module allows custom data fields to be defined for entity types (including content items, comments, user accounts, and taxonomy terms). [...]

Concrete suggestion for the Field UI module:

About:
The Field UI module provides an administrative user interface (UI) for attaching and managing fields. Field types (text, image, number, etc.) are defined by modules, and collected and managed by the Field module. The Field UI module allows you to create and attach fields to fieldable sub-types of entity types (entity types include content items from the Node module, with content types being the sub-types; taxonomy terms from the Taxonomy module, with vocabularies being the sub-types; and user accounts, with no sub-types). For more information, see the (link)online documentation for the Field UI module(/link).

Thoughts?

joachim’s picture

joachim CreditAttribution: joachim commented

+1 from me for #23.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented

...coming from #1380720: Rename entity "bundle" to "subtype" in the UI text and help

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented
Issue summary: View changes

added file module as related issue

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

RE #25 - that other issue seems to be a Drupal 9 issue about renaming the underlying developer terminology. This issue is about how to refer to them in the user interface and help documentation, which isn't really the same thing.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented

It's related and the comment serves as a note-to-self for me.

ifrik’s picture

ifrik
she/her
CreditAttribution: ifrik commented

I like the text proposed in #23 for the link module and other such modules because it focuses on the functionality of the module, and because we only need to come up with a proper wording around entities directly in the Field and Field UI module.
Those two could probably be tweaked a bit more, but that won't block any other work.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
CreditAttribution: batigolix commented

Ouch, we completely missed that D8 has an entity module that would need a proper help text as well:
#2091403: Create hook_help for Entity module

This help text could be referred to by many other and thus making it easier to use the entity concept throughout the UI

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Excellent plan!

yoroy’s picture

yoroy CreditAttribution: yoroy commented
Status: Needs review » Reviewed & tested by the community
Issue tags: -Needs usability review +Usability

#23 is what we should move forward with no?

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
CreditAttribution: webchick commented
Assigned: Unassigned » jhodgdon

This has been RTBC for awhile, assigning to Jennifer to decide what to do next.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Assigned: jhodgdon » Unassigned
Status: Reviewed & tested by the community » Fixed

As far as the help text goes, we are already following these guidelines. I don't know what else needs to be done really... I'm not sure where else we'd be referring to entities and bundles in the UI, hopefully nowhere? I think I'll just mark it fixed, unless you think we need an entry in the UI text guidelines. Maybe we do, but there's nothing that specific on https://drupal.org/node/604342 ... I thought we had a whole guide on "node" vs. "content item" but I don't see it now.

Status: Fixed » Closed (fixed)
Issue tags: -Usability, -Coding standards

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

(not verified) CreditAttribution: commented
Issue summary: View changes

...added #1380720 to the related issues section.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented
Issue summary: View changes
Issue tags: +Usability, +Coding standards
Related issues: +#1380720: Rename entity "bundle" to "subtype" in the UI text and help, +#1908570: [meta] Update or create hook_help() texts for D8 core modules, +#2028799: Improve help for link module, +#2029751: Create hook_help for entity reference, +#2030713: Improve help for email module, +#2031177: Improve help for file module

...restoring tags eaten by the tag monster and moving related issues to their dedicated metadata section.