Background:
This issue is part of the task to update/create the hook_help texts of the modules for Drupal 8:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- write the hook_help function
- review d.o. docs at https://drupal.org/documentation/modules/entityreference

Files: 
CommentFileSizeAuthor
#29 entity_reference_help-2029751-29.patch2.77 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 63,726 pass(es).
[ View ]
#29 interdiff.txt2.93 KBbatigolix
#24 interdiff.txt3.1 KBbatigolix
#24 entity_reference_help-2029751-24.patch2.76 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 60,091 pass(es).
[ View ]
#22 entity_reference_help-2029751-22.patch2.73 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,813 pass(es).
[ View ]
#22 interdiff.txt1.96 KBbatigolix
#20 interdiff.txt3.79 KBbatigolix
#20 entity_reference_help-2029751-20.patch2.77 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,650 pass(es).
[ View ]
#18 interdiff.txt4.04 KBbatigolix
#18 entity_reference_help-2029751-18.patch2.73 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,461 pass(es).
[ View ]
#15 entity_reference_help-2029751-15.patch2.44 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,712 pass(es).
[ View ]
#15 diff.txt1.1 KBbatigolix
#13 entity_reference_help-2029751-10_13.patch2.12 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,836 pass(es).
[ View ]
#10 entity_reference_help-2029751-10.patch2.15 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,232 pass(es).
[ View ]
#7 entity_reference_help-2029751-7.patch2.44 KBbatigolix
FAILED: [[SimpleTest]]: [MySQL] 58,655 pass(es), 1 fail(s), and 0 exception(s).
[ View ]
#2 entity_reference_help-2029751.patch2.41 KBvollepeer
PASSED: [[SimpleTest]]: [MySQL] 57,983 pass(es).
[ View ]

Comments

vollepeer’s picture

Assigned:Unassigned» vollepeer

Working on this...

vollepeer’s picture

Assigned:vollepeer» Unassigned
Status:Active» Needs review
StatusFileSize
new2.41 KB
PASSED: [[SimpleTest]]: [MySQL] 57,983 pass(es).
[ View ]

Implemented hook_help() for the Entity Reference module.
The actual help text should be reviewed.

jhodgdon’s picture

Status:Needs review» Postponed

We need to standardize the way we refer to "entities" in the field help text. I've opened a separate issue to discuss this:
#2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI

This issue should (sorry!) be postponed until that other one is decided.

catch’s picture

Priority:Normal» Critical
catch’s picture

Status:Postponed» Needs review

That's been downgraded to normal so unpostponing this one.

jhodgdon’s picture

Status:Needs review» Needs work

This patch doesn't really follow the proposed standards on #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI. We should also avoid in this help describing the basics of fields or of how to do field stuff, and instead refer people to the Field and Field UI help modules.

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.44 KB
FAILED: [[SimpleTest]]: [MySQL] 58,655 pass(es), 1 fail(s), and 0 exception(s).
[ View ]

Attached patch addresses points from #6

Status:Needs review» Needs work

The last submitted patch, entity_reference_help-2029751-7.patch, failed testing.

jhodgdon’s picture

There are still some problems with this text:

a) Grammar point: "defines a field type for the Field module, that lets " : that -> which

b) This is garbled: lets you create links... within Drupal manage -- what is Drupal manage?

c) The link to the online docs is not following our hook_help standards.

Well there are a lot of other obvious typos. Please proofread the help and submit a new patch. Make sure to read it through before submitting. Thanks!

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.15 KB
PASSED: [[SimpleTest]]: [MySQL] 59,232 pass(es).
[ View ]

Apologies. I must have been tired, sleeping, drunk, drugged or brain damaged (most probably a combination of those 5).

batigolix’s picture

And I have not yet replaced url() by the $generator thing, because that makes my local installation crash

jhodgdon’s picture

Status:Needs review» Needs work

Better!

(a) and (c) from #9 still apply, however.

And I think the Uses section could use some rewriting.

In the first Uses bullet, ... we've already stated that it's a field in "About", so why do we need to conclude "therefore add a field" in the Uses section? It just doesn't make sense to me. Didn't we come up with some standard ways to document field modules? Let's use those here.

In the second Uses bullet, ... It doesn't seem like "but" is the right conjunction here -- these are just two equally valid possibilities for display, not "You could do this, but if you did, ...". Maybe "Alternatively"? And I don't think the wording on that second sentence is at all clear. I know what it is trying to say, but I don't think it gets the point across?

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.12 KB
PASSED: [[SimpleTest]]: [MySQL] 58,836 pass(es).
[ View ]

Patch:

- adapts urls to new standards
- attempts to fix comments from #12

I used fields module help text, which was intensively reviewed as a guideline for the about sections.

The 2nd bullet is hard to describe, while it is so simple when you see it in the UI

jhodgdon’s picture

Status:Needs review» Needs work

Looking pretty good! A few minor things:

a) "defines a field type which lets you create links" which -> that

b) On other field modules, we have a Uses item explaining what field settings and display settings are. This is missing here.

Looks good other than that!

batigolix’s picture

StatusFileSize
new1.1 KB
new2.44 KB
PASSED: [[SimpleTest]]: [MySQL] 58,712 pass(es).
[ View ]

Patch fixes a) and b) from #14

I kind of merged the the explanation about settings and display with the already exisitng display paragraph (see the diff file)

batigolix’s picture

Status:Needs work» Needs review

Setting status

jhodgdon’s picture

Status:Needs review» Needs work

(a) is still not fixed from #14. And I think the item about the display and field settings should come first in Uses?
Then the "adding" item can say whether the things referenced are display or field settings.

Also, I think it's best to use the standard "display and field settings" item in Uses, and then have a separate item that talks about the specific display settings, rather than merging them into one Uses item?

Finally, maybe we should have a link to the Entity module help (which may not exist yet but which we expect will explain what entities are?).

batigolix’s picture

Issue summary:View changes
Status:Needs work» Needs review
StatusFileSize
new2.73 KB
PASSED: [[SimpleTest]]: [MySQL] 59,461 pass(es).
[ View ]
new4.04 KB

Patch addresses the points in #17.

Furthermore I added an example of the use of an entity reference field in the About section

We should also try to improve https://drupal.org/documentation/modules/entityreference

jhodgdon’s picture

Status:Needs review» Needs work

Great work - go batigolix ! You must be on a personal "fix all the hook_help" sprint these past few days. :)

I noticed a new thing to fix: We shouldn't be using the word "node" -- say "content item".

And I think maybe my idea about reordering the Uses items didn't work very well.. the intention was that in the Adding bullet point, it would reference field settings, but it doesn't actually say those are field settings... Really, we don't need an "Adding" bullet point anyway -- adding a field is covered by the Field UI module, and it is fairly generic. We should instead have a bullet point with the word "settings" in its heading, maybe "Configuring entity reference field settings"? There we would talk about the settings, and leave out the stuff about how to add the field?

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.77 KB
PASSED: [[SimpleTest]]: [MySQL] 59,650 pass(es).
[ View ]
new3.79 KB

one patch a day ... ;)

I changed the "node" bit

Agree the Uses section is a bit vague.

The patch includes a new attempt. I followed the help text we did for the Link field module: one general paragraph about fields, followed by the specifics for the entity ref field.

I think there coulkd still be improvements in the way we refer to the reference field and the entities. It is all a bit abstract ...

Have a look.

jhodgdon’s picture

Status:Needs review» Needs work

On the same Coding Standards page that says not to use "Node", it says not to use "Drupal" either:
https://drupal.org/node/604342#wording

That aside, I think this latest patch is looking good! One other thought:

The parenthetical remark in About that says where to learn about entities and fields... I think it is more related to the first sentence than the second sentence? So let's either (1) put it in the first sentence or (2) take out the parens and combine it with the "for more information" last sentence? It just doesn't seem related to the sentence it is currently inside.

I think this is nearly ready to go! Thanks!

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new1.96 KB
new2.73 KB
PASSED: [[SimpleTest]]: [MySQL] 59,813 pass(es).
[ View ]

In patch #20 there is no mention of Drupal or Node anymore.

I did re-order the help text quite a bit between #18 and #20 .

Could you check / review again?

In the attached patch I tried to solve your second point by putting all the references to documentation in the final phrase of the About section. I was thinking of putting just 2 links on the words fields and entities in the 1st phrase, but that might not be explicit enough. What do you think?

jhodgdon’s picture

Status:Needs review» Needs work

RE mentions of Drupal -- the end of the first sentence of About. Node was never there.

I think the current patch is really good, except that mention of Drupal. And also since we are now differentiating between field settings and display settings, I think we need to say "in the field settings" in the "Filtering and sorting" item,

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.76 KB
PASSED: [[SimpleTest]]: [MySQL] 60,091 pass(es).
[ View ]
new3.1 KB

patch addresses points in #23

jhodgdon’s picture

Issue tags:+Needs manual testing

Excellent work! I think this one is ready for a quick manual test:
- Verify that all the links work
- Verify that all mentions of pages/text within the UI match what is seen in the UI
- Verify that the formatting is OK.

batigolix’s picture

Component:documentation» entity system
Issue tags:+Novice
Parent issue:» #1908570: [meta] Update or create hook_help() texts for D8 core modules
amitaibu’s picture

Component:entity system» entity_reference.module

Thanks @batigolix text looks really good :)

jhodgdon’s picture

Status:Needs review» Needs work

I gave this a manual test today and I think it is all looking good except for one very minor item in About:

"see the online documentation for the Entity Reference module, the Entity module help page and the Field module help page."

There should be a comma before "and" here.

And technically, in the Display section, you can display the entity label with or without a link, and there are other display choices as well (which I guess we don't really need to mention).

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new2.93 KB
new2.77 KB
PASSED: [[SimpleTest]]: [MySQL] 63,726 pass(es).
[ View ]

Comma & "with or without link" fixed

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

Thanks! Let's get this one in.

jhodgdon’s picture

Component:entity_reference.module» documentation

Back to documentation component in case I am doing commits before someone else gets to it. (I only look at issues in Documentation when I'm doing commits.)

jhodgdon’s picture

Status:Reviewed & tested by the community» Fixed

Thanks again! Committed to 8.x.

Status:Fixed» Closed (fixed)

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