Create hook_help for HAL module

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

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.

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

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.

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.

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

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

The other issue was downgraded to normal. Unpostponing.

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.

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)

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.

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.

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

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.

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?

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

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?

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.

Who did the remaining tasks like reviewing the docs?

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.

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

Committed and pushed to 8.x. Thanks!

Woot!!