Background:
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

Tasks:
- review / write the hook_help text according to help guidelines

Files: 
CommentFileSizeAuthor
#20 interdiff.txt3.63 KBbatigolix
#20 text-updated_help_d8-documentation.2091461-20.patch4.17 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,705 pass(es).
[ View ]
#18 text-updated_help_d8-documentation.2091461-18.patch4.17 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 59,177 pass(es).
[ View ]
#18 interdiff-2091461-15-18.txt1.99 KBifrik
#16 text-updated_help_d8-documentation.2091461-15.patch4.16 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 59,058 pass(es).
[ View ]
#12 interdiff-2091461-10-12.txt4.89 KBifrik
#10 text-updated_help_d8-documentation.2091461-10.patch3.04 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,993 pass(es).
[ View ]
#10 interdiff-2091461-5-10.txt2.83 KBifrik
#8 text-updated_help_d8-documentation.2091461-8.patch0 bytesifrik
PASSED: [[SimpleTest]]: [MySQL] 59,453 pass(es).
[ View ]
#8 interdiff-2091461-5-8.txt2.82 KBifrik
#6 text-updated_help_d8-documentation.2091461-5.patch3.26 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,580 pass(es).
[ View ]
#6 interdiff-2091461-2-5.txt3.33 KBifrik
#2 text-updated_help_d8-documentation.2091461-2.patch1.77 KBpetrpo
PASSED: [[SimpleTest]]: [MySQL] 58,630 pass(es).
[ View ]

Comments

petrpo’s picture

Trying to correct it according to standards

petrpo’s picture

Status:Active» Needs review
StatusFileSize
new1.77 KB
PASSED: [[SimpleTest]]: [MySQL] 58,630 pass(es).
[ View ]
berkas1’s picture

Looks OK

ifrik’s picture

I'll work further on this to bring it inline with other field modules.

jhodgdon’s picture

Status:Needs review» Needs work

Yes, this still needs work. Check out the help for the Link or Telephone modules for examples.

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new3.33 KB
new3.26 KB
PASSED: [[SimpleTest]]: [MySQL] 58,580 pass(es).
[ View ]

Yes, I was just on it right now :)

Lots of the options that were available in D7 have been removed: it's not possible anymore to choose between field with or without summaries etc.

The text formats page changes it's name depending on whether the text editor module is enabled or not - but since it is now impossible to disable a module in D8, this module is enabled by default, so we might just as well refer to the page as "Text formats and editors".

jhodgdon’s picture

Status:Needs review» Needs work

Yes, it is impossible to *disable* a module, but you can still *uninstall* a module. But I think it's probably OK to leave that reference as it is.

Anyway, this mostly looks good! A few typographical/grammatical fixes would help:

a)

or allow users to formated text.

formated -> format

b)

Text formats and editors page </a>.

Extra space in the A link text.

c) "formated" is misspelled. Should be "formatted".

d) Heading "Setting and display the text length"... This doesn't make sense to me. Reading what is in that item, maybe it should be just "Setting the text length"?

e) You can change the number of characters that define the maximum text length
This could be simplified to say "You can set the maximum text length"

f) can be entered on the  <em>Manage Extra space before the EM tag.

g) I do not think it is clear in the last Uses point what the difference is between the maximum text length and the size of the form field.

h) choose whether to displayed a trimmed version of the text, and if so after how many characters the text should be cut off.
- displayed -> display
- And that last phrase... would be better as "and if so, where to cut off the text"

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new2.82 KB
new0 bytes
PASSED: [[SimpleTest]]: [MySQL] 59,453 pass(es).
[ View ]

Thanks for the comments.
In the last item, I wanted to explain that changing the length of the form doesn't impact on the allowed text length - but thinking about it: that's a general issue that needs to be explained in the field help pages.

jhodgdon’s picture

Status:Needs review» Needs work

The patch file is empty. Can you re-upload?

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new2.83 KB
new3.04 KB
PASSED: [[SimpleTest]]: [MySQL] 58,993 pass(es).
[ View ]

not sure what happened there but here it is again

jhodgdon’s picture

Status:Needs review» Needs work

So... In reading this one more time, I'm a bit concerned about the first line of About. I think we should list the actual field types rather than saying "various" maybe? List the names someone would see in the Field UI and maybe add a brief explanation of what each one is? I don't know... it is possibly OK as it is.

Other than that... looks pretty good! I noticed a typo:
"You can set change the maximum text length"

And the Text with Summary field has some additional options that should maybe be described?

ifrik’s picture

Issue summary:View changes
StatusFileSize
new4.16 KB
PASSED: [[SimpleTest]]: [MySQL] 59,009 pass(es).
[ View ]
new4.89 KB

I added more specific details on long text fields and on summaries. Therefore I also changed the order of the items.
Due to a bug, the text editor is not displayed on the short text field: #2143085: No text editor displayed for Text field. I assume that the text editor is supposed to work the same on the short and long fields, but this should be checked again nonetheless.

ifrik’s picture

Status:Needs work» Needs review
jhodgdon’s picture

Status:Needs review» Needs work

This help text overall seems very good to me! There are a few minor grammatical things that need fixing in this patch:

a) This sentence no verb (start of About):
"The Text module allows you to short and long text fields with optional summaries."

b) In Uses item 1:
"If you choose Text as field type on the Manage fields page,"
needs "the" before "field type"

c) Uses item 2:
" you can set the number of rows that is displayed to users."
is -> are

d) Uses item 4:
"choose whether to display a trimmed version of the text, and if so, where to cut off the text."
Normally I think "whether" should have an alternative, so it should be "whether ... or ...", but there is no "or" alternative given. Maybe just leave out the word "whether"?

e) Uses item 5:
"In order to display a summary that is different from the trimmed beginning of text"
This seems very awkward to me. Maybe:
"As an alternative to using a trimmed version of the text, you can choose to enter a separate summary by ..."

f) Uses item 5:
"by choosing the appropriate format on the Manage Display page."
There is an extra space between "the" and "appropriate"

g) Last Uses item:
"by choosing Plain text as Format on the Manage Display page."
Needs "the" before "Format".

ifrik’s picture

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new5.72 KB
new4.16 KB
PASSED: [[SimpleTest]]: [MySQL] 59,058 pass(es).
[ View ]

Thanks for the comments. I've included them.

jhodgdon’s picture

Status:Needs review» Needs work

Excellent!

One thing:

As an alternative to using a trimmed version of the text, you can enter a separate summary by choosing the Long text with summary format on the Manage Fields page.

I don't think this is a "format" -- isn't it a "field type"?

Other than this small thing, I think this is ready to go (it will still need a manual test however). Thanks!

ifrik’s picture

Status:Needs work» Needs review
StatusFileSize
new1.99 KB
new4.17 KB
PASSED: [[SimpleTest]]: [MySQL] 59,177 pass(es).
[ View ]

So many managing pages... yes, that should have been field type. I've changed it.

jhodgdon’s picture

Issue tags:+Needs manual testing

Excellent, thanks! I think this is ready for someone to give it a manual test:
- Verify that the formatting is good.
- Verify that all the links work.
- Verify that where specific page names, tab names, labels, etc. are mentioned in the help text, they match what a user actually sees on the screen.

batigolix’s picture

StatusFileSize
new4.17 KB
PASSED: [[SimpleTest]]: [MySQL] 59,705 pass(es).
[ View ]
new3.63 KB

- formatting is good
- all the links work.
- specific page names, tab names, labels, etc. are correct but I had to change the case to make them match correctly

The last submitted patch, 20: text-updated_help_d8-documentation.2091461-20.patch, failed testing.

The last submitted patch, 20: text-updated_help_d8-documentation.2091461-20.patch, failed testing.

jhodgdon’s picture

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

Looks good, thanks! Assuming the tests pass this time (the failure seemed to be totally unrelated), I think this is ready to go in.

jhodgdon’s picture

Status:Reviewed & tested by the community» Fixed
Issue tags:-Needs manual testing

Thanks again everyone! Committed to 8.x.

Status:Fixed» Closed (fixed)

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