Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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/hal
Related to #2009530: Improve hal.module (user-facing) name and description
Comment | File | Size | Author |
---|---|---|---|
#18 | drupal8.hal-module.2029755-18.patch | 1.33 KB | clemens.tolboom |
#24 | drupal8.hal-module.2029755-24.patch | 1.4 KB | batigolix |
#19 | drupal8.hal-module.2029755-19.patch | 1.34 KB | batigolix |
#16 | 2029755-16-hal-help.patch | 1.33 KB | batigolix |
#13 | 2029755-hal-help.patch | 1.12 KB | linclark |
Comments
Comment #1
batigolixI doubt if we need help text for this module as there is no UI of any sort
Comment #2
catchNo we do need help text, even if it's to explain that it's an API module and has no UI.
Comment #3
batigolixFirst patch. Text is almost complete nonsense, but it might get the conversation started. I really have no clue what this module is about (even after reading http://stateless.co/hal_specification.html)
Comment #4
batigolixSee also #2009530: Improve hal.module (user-facing) name and description
Comment #5
linclark CreditAttribution: linclark commentedI would prefer something concise which does not go into depth about the format. If someone wants to read up on the format, they can follow the link. We should also be sure to use "Hypertext", not "Hypermedia", in the name.
Comment #6
linclark CreditAttribution: linclark commentedComment #7
jhodgdonSo... Why would someone actually want to use this module, and what would they use it for? The help text should tell me about that. I was going to move this issue to the module component so the maintainers can propose better text, but I don't see this module in the component list...
Comment #8
linclark CreditAttribution: linclark commentedI am the maintainer. I filed an issue to have it added to the component list, but it just sat in the queue #1942216: Add hal.module component to core issue queue.
You would use this module if you were setting up an API to expose the content on your site and you wanted that API to support hypermedia.
Comment #9
linclark CreditAttribution: linclark commentedHow about if we add a sentence explaining Hypermedia APIs:
Hypermedia APIs are a style of Web API which use URIs to identify resources and the links between them, enabling API consumers to follow links to discover API functionality. Hypertext Application Language (HAL) is a format which supports the linking required for hypermedia APIs. This module adds support for serializing entities to the JSON version of HAL.
Comment #10
linclark CreditAttribution: linclark commentedmarking as needs review for Jennifer... let me know if that's clearer. If it is, I'll post a patch.
Comment #11
jhodgdonLooks good to me... although we haven't yet figured out how to describe "entities" in the Drupal 8 UI or help. There's a separate issue on that... I guess we should postpone this one until that other issue is decided, sigh.
#2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI
Comment #12
catchThe other issue was downgraded to normal. Unpostponing.
Comment #13
linclark CreditAttribution: linclark commentedJust changed the text to match what I had in #9, which jhodgdon said looked good to her. I also changed the @file comment, since this is no longer just an empty module file.
Comment #14
jhodgdonYeah, still looks pretty good!
Minor grammar point: "...is a format which supports the ..." which -> that
Also, I think when we refer to "entities" in help, we want to say something like "entities (such as content items, taxonomy terms, etc.)" to clarify what the word means. See issue linked in #11 for discussion.
And one more thing: our standard for writing help files in Drupal Core is that they should refer to the on-line help page for the module (which should be created as at least a stub). (http://drupal.org/node/632280)
Comment #15
jhodgdonI guess the other question I would have about this module after reading the help (which is all I know about it)... Is it just an API module, or does it actually modify Drupal output in some way? That should probably be described in "Uses", one way or another.
Comment #16
batigolixAttached patch fixes the points from #14.
The question from #15 still needs answering.
Comment #17
jhodgdonThere are still some issues in this patch:
a) Minor grammatical point:
"Hypermedia APIs are a style of Web API which use URIs..." : which -> that
b) For accessibility, link text needs to be descriptive of what is being linked to, or if not, the link needs a title attribute. I think this is not a great link in that regard:
The URL is to a Wikepedia article on link relations, so "links" is not descriptive link text.
c) Extra space in
"online documentation for the HAL module"
d) #15 is still not addressed. How do you use this module and what does it really do? Does it require another module to actually do something, or does it do something itself?
e) This text is still kind of confusing to me: "enabling API consumers to follow links to discover API functionality.". That sounds like the links are pointing out an API, when really I think what is discovered is the relationship between the items that are linked... maybe? Anyway, this text did not explain ot me what someone who followed a link would actually discover.
Comment #18
clemens.tolboom<p>Hypermedia APIs are a style of Web API which use URIs to identify
that uses ? It seems plural to me.
According to #2009530-7: Improve hal.module (user-facing) name and description we should not use "Hypermedia APIs" but "Hypertext Application Language"
As the help is about explaining HAL I prefer the tree lines interchanged. And adding some paragraph would not harm either.
Hypertext Application Language (HAL) is a format that supports the linking required for hypermedia APIs.
Hypermedia APIs are a style of Web API which use URIs to identify resources and the links between them, enabling API consumers to follow links to discover API functionality.
This module adds support for serializing entities (such as content items, taxonomy terms, etc.) to the JSON version of HAL. For more information, see the online documentation for the HAL module.
Comment #19
batigolixThis patch:
- removes the paragraphs introduced in #18. They are not according to the standards and they make the strings harder to translate.
- fixes b) & c) from #18
Still open are d) and e) from #18.
Comment #20
linclark CreditAttribution: linclark commentedComment #21
clemens.tolboom@batigolix what standards?
I hate Drupal help texts as they are mostly long lines without paragraphs which made them hard to read. Adding paragraph would help a lot.
Should we change the standards for better UX?
Comment #22
batigolixThese standards: https://drupal.org/node/632280 . But there is no explicit instruction for the use of paragraphs.
I checked the hook_help of +/- 15 modules and only one ("update") had paragraph markup inside the About section, which seems to be a bit of an exception because the text after the paragraph marker is only shown in certain situations. So it seems to be the custom to write the about section as one paragraph.
But I am, of course, not against improving readability.
It is also a custom to keep the
<p>
tag outside of the t() function.Another issue:
I see my patch at #19 stupidly outputs 2
<p>
tags:Comment #23
jhodgdonI think that a multi-paragraph About section is fine, but yes, please put the P tags outside of t().
Comment #24
batigolixpatch:
- introduces paragraphs
- removes double
<p>
Comment #25
jhodgdonChanging the one-line description at the top of the file is an excellent idea. I think the one-line description in the hal.info.yml file should also be changed to say "adds support for" instead of "serializes"? (That one-line description probably can use the acronym HAL, since the module name is given as "HAL (Hypertext Application Language)" and I think the description would never appear apart from the module's name.)
Other than that small detail, I think this format and text is really clear. Can we get a final review from the HAL module maintainers? And can someone test manually to make sure it looks OK and the links all go to an appropriate page?
Comment #26
clemens.tolboomAll 3 links are manual tested and point to the correct location.
We can RTBC this I think as changes to the YAML file are done by #2009530: Improve hal.module (user-facing) name and description.
Comment #27
clemens.tolboomWho did the remaining tasks like reviewing the docs?
Comment #28
jhodgdonI have reviewed the doc text for clarity and grammar/punctuation. clemens.tolboom has manually tested the links.
We still need the HAL module maintainers to review it for accuracy.
Comment #29
linclark CreditAttribution: linclark commentedI am the only HAL module maintainer, and this looks fine to me.
Comment #30
webchickCommitted and pushed to 8.x. Thanks!
Comment #31
jhodgdonWoot!!
Comment #32.0
(not verified) CreditAttribution: commentedAdded XREF https://drupal.org/node/2009530