The hook_help text for the file module needs improving, and appropriate wording in the about section once this has been decided. #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI

Files: 
CommentFileSizeAuthor
#18 interdiff-2031177-16-18.txt3.56 KBifrik
#18 file-help-text-2031177-18.patch5.55 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 59,195 pass(es).
[ View ]
#16 file-help-text-2031177-16.patch5.56 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,589 pass(es).
[ View ]
#16 interdiff-2031177-10-16.txt5.93 KBifrik
#15 file-help-text-2031177-15.patch5.11 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,574 pass(es).
[ View ]
#15 interdiff-2031177-10-15.txt5.11 KBifrik
#10 file-help-text-2031177-10.patch5.98 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,918 pass(es).
[ View ]
#7 file-help-text-2031177-7.patch6.04 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,681 pass(es).
[ View ]
#7 diff.txt3.99 KBbatigolix
#3 file-help-text-2031177-3.patch6.2 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,008 pass(es).
[ View ]
#3 interdiff-203117-1-3.txt9.02 KBifrik
#1 file-help-text-2031177-1.patch7.59 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,482 pass(es).
[ View ]

Comments

ifrik’s picture

StatusFileSize
new7.59 KB
PASSED: [[SimpleTest]]: [MySQL] 58,482 pass(es).
[ View ]

I've rewritten the help text, following the same pattern as the #2028799: Improve help for link module. It's still postponed until we have a good wording for entities #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI.
I'm not sure whether the list for the four different formatting options is the best way to do it, or whether they should be listed as separate items instead.

jhodgdon’s picture

Thanks! A few things to look at:
- There's at least one place in the new text where it refers to a "link field" instead of a "file field".
- The help still refers to content types, but let's leave that fix until we decide on the entities wording.
- Maybe the two sections about display-related settings should be combined or at least put nearer to each other?
- Same for the 3 sections about where to store the files?
- I don't think it makes sense to refer to "file types" when really all that is controlled is extensions.
- "By default this description text will be used instead of the file name."... Um... By default what is used where? when? I think this is misleading. Either leave it out or be more precise (better I think to leave it out and let the Display section describe what actually happens, which is rather complicated and depends on what display settings are chosen).
- Grammar nitpick in the Display section: "displays the files as a link" -- should either be "each file as a link" or "the files as links".
- Another grammar nitpick in the next sentence: "If descriptions are enabled and submitted, this is displayed instead of the file name." --> "this" refers to what? I think it is referring to "descriptions", in which case it should be "they".
- And for the rest of this paragraph, similarly be careful about singular/plural and keep it consistent. It's not well worded and caused me difficulty in reading it because of lack of this precision.

ifrik’s picture

StatusFileSize
new9.02 KB
new6.2 KB
PASSED: [[SimpleTest]]: [MySQL] 58,008 pass(es).
[ View ]

Rewritten help text extensively by adding the appropriate wording for fields and by pulling the different uses together.
The second paragraph under Storing files comes from the original help text. It would better fit into a help for the File system because it is relevant even when the File module is not enabled. However, I could not find a help page for this. If it is to stay here, then it needs editing to make the reference more generic.

ifrik’s picture

Status:Postponed» Needs review
jhodgdon’s picture

Status:Needs review» Needs work

We don't have help pages for topics that are not modules - that is a limitation of the hook_help() antiquated help system. You can add something to the System module help though, if you have information about the file system. I agree it doesn't belong in the File module help.

A few other thoughts:
- Can we use our standard wording for the link to the online documentation please?
- Still refers to Link instead of File fields in places.
- Indentation is off in the code.
- Needs some grammatical attention here and there.

I didn't review this thoroughly since it seemed like part of the text was destined to go away.

jhodgdon’s picture

http://drupal.org/node/632280 has the standards for help docs by the way, for the link to the online docs.

batigolix’s picture

Component:documentation» file.module
Assigned:ifrik» Unassigned
Status:Needs work» Needs review
StatusFileSize
new3.99 KB
new6.04 KB
PASSED: [[SimpleTest]]: [MySQL] 58,681 pass(es).
[ View ]

Patch:

- changes url() to \Drupal::url()
- changes token from @link to !link
- rewrites the point 'Storing files' in section 'Uses' to be in line with the D8 UI changes for the file system settings
- fixes references to Link field
- use standard wording for link to Docs

Also:
- changed component to file.module so maintainers may notice the issue
- unassigned from ifrik

jhodgdon’s picture

Status:Needs review» Needs work

Thanks! Looking better... Still a few problems:

a) There is an indentation problem in this patch, in this line:

+$output .= '<dd>' . t('The <em>settings</em> and the <em>display</em> of the file field can be configured separately. See the <a href="!field_ui">Field UI help</a> for more information on how to manage fields and their display.', array('!field_ui' => \Drupal::url('system.file_system_settings'))) . '</dd>';

b) In the same line, this URL is incorrect. The A tag says it is going to the Field UI help page, but that is not where the URL goes.

c) Needs copy editing, such as " upload files with these extension" and "list of allowed file extension" (both should be "extensions").

d) I think it is confusing in the second Uses item to refer to the "file extension field" -- "field" is used both to refer to a File Field and this data entry field. Maybe this can be reworded so it doesn't use the word "field" for a settings entry, like calling it the "file extension setting"? The same goes for other settings descriptions. We've gone to the trouble of saying in the first bullet point that there are field settings and display settings, so let's use this terminology in the rest of the help? It's not clear in the Uses section, otherwise, which are display and which are field settings.

e) The Storing Files item starts out by stating that files are stored in a public directory. Then later on it contradicts this by talking about private storage. This is confusing. Also, I think we shouldn't explain what private/public files are here -- it should be explained in the System module help and a link should be made here, with some text saying something like "You can choose whether to use private or public file storage in the field settings. For more information about file storage, see blah blah blah"

f) The UL list in the last Uses item is not valid HTML. There are no closing LI tags (or at least, some are missing).

jhodgdon’s picture

Regarding (d), this text from the Link module issue is a good way to do this, I think:

+      $output .= '<dt>' . t('Adding link text') . '</dt>';
+      $output .= '<dd>' . t('In the field settings you can define a link text to be optional or required in any link field.') . '</dd>';
batigolix’s picture

StatusFileSize
new5.98 KB
PASSED: [[SimpleTest]]: [MySQL] 58,918 pass(es).
[ View ]

patch:

- fixes a) b) c) f) from #8
- rewrites 2nd item in Uses (d #8)

Regarding point e) in #8: Is the concept of private and public files explained elsewhere so we can link there? The only place I can think of would be the help text of the system.

batigolix’s picture

Status:Needs work» Needs review

setting status

Status:Needs review» Needs work

The last submitted patch, file-help-text-2031177-10.patch, failed testing.

jhodgdon’s picture

Right. The System module help should describe the file system set-up. Both File and Image modules (and maybe others) can then reference this text. If System doesn't currently do that, then this issue could also patch the System module help so that it does.

I reviewed the patch in #11... Most of the Uses bullet points still talk about "fields" on the file field's settings and display settings, which I still think is confusing. I like how the File Extensions item is reworded. Can you do something similar for the others?

ifrik’s picture

Status:Needs work» Needs review

#10: file-help-text-2031177-10.patch queued for re-testing.

ifrik’s picture

StatusFileSize
new5.11 KB
new5.11 KB
PASSED: [[SimpleTest]]: [MySQL] 58,574 pass(es).
[ View ]

I've rewritten the last item to refer to field and display settings. Added commas in the About and File extention item, and removed some trailing white space.
Deleted the text about storing files, but propose that text to the system module.

ifrik’s picture

StatusFileSize
new5.93 KB
new5.56 KB
PASSED: [[SimpleTest]]: [MySQL] 58,589 pass(es).
[ View ]

Of course the section about storing files shouldn't have been completely removed... Added it again with the relevant links to the File System and System help pages.
The interdiff is for the difference to Patch #10 because nobody had reviewed patch #15 yet anyway.

jhodgdon’s picture

Status:Needs review» Needs work

This looks pretty good, thanks!

There are a few minor language/usage/punctuation issues that should be fixed:

a) Can you use "for example" instead of "e.g."? "e.g." is not punctuated correctly here (hardly ever is), and it is difficult for translators to deal with.

b) "you can define which are the allowed file extensions"... Would be better to say "you can define the allowed file extensions"

c) "System help page" --> System module help page

d) "entering the appropriate value into the Maximum upload size field." --> Let's not use the word "field" here for a setting, as it is confusing when we're talking about a file field. How about "entering the desired value for the Maximum upload size setting"?

ifrik’s picture

Issue summary:View changes
Status:Needs work» Needs review
StatusFileSize
new5.55 KB
PASSED: [[SimpleTest]]: [MySQL] 59,195 pass(es).
[ View ]
new3.56 KB

I've changed the wording as proposed in comment #17.

jhodgdon’s picture

Issue tags:+Needs manual testing

Thanks! This looks good to me.

The help still needs manual testing:
- Make sure it is formatted OK
- Test that all the links work
- If there is mention of any text that is part of the UI (such as names of settings, names of modules, etc.), make sure it matches what the user sees in the UI.

slashrsm’s picture

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

I performed steps from #19. It looks good to me.

jhodgdon’s picture

18: file-help-text-2031177-18.patch queued for re-testing.

jhodgdon’s picture

Component:file.module» documentation
Status:Reviewed & tested by the community» Fixed

Thanks again all who worked on this! Committed to 8.x.

Status:Fixed» Closed (fixed)

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