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

Files: 
CommentFileSizeAuthor
#18 drupal8.hal-module.2029755-18.patch1.33 KBclemens.tolboom
PASSED: [[SimpleTest]]: [MySQL] 59,187 pass(es).
[ View ]
#24 drupal8.hal-module.2029755-24.patch1.4 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,537 pass(es).
[ View ]
#19 drupal8.hal-module.2029755-19.patch1.34 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 58,824 pass(es).
[ View ]
#16 2029755-16-hal-help.patch1.33 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,214 pass(es).
[ View ]
#13 2029755-hal-help.patch1.12 KBlinclark
PASSED: [[SimpleTest]]: [MySQL] 57,919 pass(es).
[ View ]
#3 create-help-text-hal-2029755-3.patch1.14 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 56,943 pass(es).
[ View ]

Comments

batigolix’s picture

I doubt if we need help text for this module as there is no UI of any sort

catch’s picture

Priority:Normal» Critical

No we do need help text, even if it's to explain that it's an API module and has no UI.

batigolix’s picture

Status:Active» Needs review
StatusFileSize
new1.14 KB
PASSED: [[SimpleTest]]: [MySQL] 56,943 pass(es).
[ View ]

First 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)

batigolix’s picture

linclark’s picture

I 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.

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 variant of HAL.

linclark’s picture

Status:Needs review» Needs work
jhodgdon’s picture

So... 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...

linclark’s picture

I 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.

linclark’s picture

How 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.

linclark’s picture

Status:Needs work» Needs review

marking as needs review for Jennifer... let me know if that's clearer. If it is, I'll post a patch.

jhodgdon’s picture

Status:Needs review» Postponed

Looks 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

catch’s picture

Status:Postponed» Needs review

The other issue was downgraded to normal. Unpostponing.

linclark’s picture

StatusFileSize
new1.12 KB
PASSED: [[SimpleTest]]: [MySQL] 57,919 pass(es).
[ View ]

Just 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.

jhodgdon’s picture

Status:Needs review» Needs work

Yeah, 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)

jhodgdon’s picture

I 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.

batigolix’s picture

Component:documentation» hal.module
StatusFileSize
new1.33 KB
PASSED: [[SimpleTest]]: [MySQL] 59,214 pass(es).
[ View ]

Attached patch fixes the points from #14.

The question from #15 still needs answering.

jhodgdon’s picture

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

and the <a href="@link_rel">links</a> between them

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.

clemens.tolboom’s picture

StatusFileSize
new1.33 KB
PASSED: [[SimpleTest]]: [MySQL] 59,187 pass(es).
[ View ]

<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.

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new1.34 KB
PASSED: [[SimpleTest]]: [MySQL] 58,824 pass(es).
[ View ]

This 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.

linclark’s picture

According to [#2009530#7] we should not use "Hypermedia APIs" but "Hypertext Application Language"

This is probably confusing. Hypermedia APIs are a different thing from the Hypertext Application Language, so we should still use both. However, we should not use Hypermedia Application Language.

clemens.tolboom’s picture

They are not according to the standards

@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?

batigolix’s picture

Status:Needs review» Needs work

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

$output .= '<p>' . t('<p><a hr ....
jhodgdon’s picture

I think that a multi-paragraph About section is fine, but yes, please put the P tags outside of t().

batigolix’s picture

Status:Needs work» Needs review
StatusFileSize
new1.4 KB
PASSED: [[SimpleTest]]: [MySQL] 58,537 pass(es).
[ View ]

patch:

- introduces paragraphs
- removes double <p>

jhodgdon’s picture

Changing 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?

clemens.tolboom’s picture

All 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.

clemens.tolboom’s picture

Who did the remaining tasks like reviewing the docs?

jhodgdon’s picture

I 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.

linclark’s picture

Status:Needs review» Reviewed & tested by the community

I am the only HAL module maintainer, and this looks fine to me.

webchick’s picture

Status:Reviewed & tested by the community» Fixed

Committed and pushed to 8.x. Thanks!

jhodgdon’s picture

Woot!!

Status:Fixed» Closed (fixed)

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

Anonymous’s picture