Improve help for link module

Thanks... I'm not sure that the items here are really "uses" of the Link module. The Link module is a field used to display links. The "uses" listed here are just the specifics of how to configure that field, and I don't think they really need to be described as separate "uses". Maybe... I could be convinced. :) But maybe the uses should just say "Configuring the field" and "Configuring field display", and list what can be done in each of these categories of "uses"?

I'm also not certain that the Drupal 8 core Link module supports all of the options you have stated in this help, or that they are on the same URL paths as they were in Drupal 7. Did you actually test this in Drupal 8?

Finally.... If we do want to add this text, there are some formatting issues in the patch (indentation in the code) and grammatical issues in the text (the main one I saw is that the word "text" as used in "link text" is not a countable noun, so it should not be made plural into "link texts").

Thoughts?

This issue is just as important as any other documentation issue! Patches improving documentation are always welcome. I appreciate your efforts now, and others will appreciate it down the road. :)

So... This is looking better! I still think it can use some improvement:

a) I noticed the link to the on-line help is using http://drupal.org but I think it should probably be https now?

b) In the same way that "link text" cannot be made plural because it is not a countable noun, it also cannot be counted as the number one, for instance: "a link text". Just say "link text" without the "a". For example: "To enable the addition of a link text" should be "To enable the addition of link text". Also, I'm still seeing "texts" in the Placeholders section. It should just be "text". (The countable word "texts" means something like "books or documents", not "little pieces of text".)

c) I still think this would be clearer if it separated the "manage" operations from the "display" operations. How about this structure:
Uses

Configuring link field settings

To configure the settings for a link field, go to [your description of how to get to Manage Fields/edit]. On this page, you can:

• Toggle whether link text is entered: ...
• Use placeholders: ...

Configuring link field display

To configure the display settings for a link field, go to [your description of how to get to Display Fields, including the cog]. In this dialog, you can:

• Display URL, link text, or both: ...
• Add "rel" and other attributes

This looks good! I like the text, and I think the organization is much better. A few To Dos:

a) There is a spelling error: approbriate [b>p]

b) I think we normally say to "click" links rather than "choose" links.

c) Link fields can be added to many other things besides node content types (taxonomy terms, users, etc.), now that I think about it. I'm not sure what to do about it... Maybe in the instructions for how to get to the configuration screen we should say something like "find the Manage Fields page for the content type, taxonomy vocabulary, or other [entity bundle] that your Link field is attached to. For instance, if it is attached to a content type, [the instructions you wrote]". Thoughts? Maybe you can word it better. And as a note, I'm not sure what word we are using for "entity bundle", which is the programmer term but I'm sure we are not using that in the Drupal UI.

d) Same as C for the Manage Display instructions.

e) In the Drupal project, we use serial commas. So: "option a, option b, or option c" (need a comma before "or" in "Display URL, link text or both").

f) A reviewer (other than the person who made the patch) needs to install this patch on a Drupal 8 site and verify that:
- It formats well on the help page
- The descriptions of how to do things are accurate
- The text matches the UI text
- The links work
So we should tag this issue "needs manual testing" once the known issues in the patch are taken care of.

c) I prefer to refer to entities as follows:

entity (content type, user, taxonomy term or comment) 

For example:

You can add a link field to an entity (content type, user, taxonomy term or comment) by adding a geofield. 

So in this case we might use:

To configure the settings for a link field, edit the entity (content type, user, taxonomy term or comment) and choose the Manage fields link for the content type.

You can leave the link on the word "content type" (maybe add links on the other entities. dunno if that is possible)

f) im trying to review the patch but my version of d8 is broken :(

I think your method of referring to entities is good, batigolix... but your preference and my preference are not exactly what matters. In the Drupal Core UI, we try to be consistent. So we need to figure out what the Usability Team has decided to standardize on.

Also, we do have a standard for serial commas, so it would be "... taxonomy term, or comment...". :)

And in your last example:
"To configure the settings... Manage fields link for the *entity*" (not *content type*) right?

Since we have a UX text question,... actually I think we should file a separate issue to figure out how to refer to entities in the UI for Drupal 8. It needs to be added to this page:
https://drupal.org/node/604342

Here's an issue:
#2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI

We should postpone this issue until this has been decided.

Yes, I think that is worth mentioning. In the first sentence, you could say "...external URLs starting with http: or https:..." for instance?

Anyway, we still need to postpone this issue due to comment #10.

I don't really like how this last change is set up very much... Can't it just be added to the About section as a short note like I suggested in #12? Having a whole section on what the Link module doesn't support in the Uses section seems like overkill, and it's also more of a "this is what it isn't used for" than a "this is what it's used for", so I don't think it belongs in "uses" at all.

We can rewrite this by explaining in the About section what kind of links and protocols are supported by the Link module, like e.g.

The Link module provides a field for external URLs (http:// or https://). The links can be displayed as URL or as a clickable link.

This looks better! A few thoughts:

a)

They must include the web protocol (http or https) in order to validate during input; other scheme names (ftp, git, etc.) are not supported.

The same concept is referred to as "web protocol" and "scheme name" in the same sentence. Choose one and stay consistent.

b) Don't put <br> in there. Either make a new paragraph or just remove it to stay in the same paragraph; in any case the correct tag would be <br />

c) The first two sentences in About seem kind of short and choppy. Maybe combine into one sentence?

d) "Links are external URLs"... I don't think a link *is* a URL, rather than it *links to* a URL. This maybe needs to be reworded?

e) The correct punctuation of "e.g." is that it nearly always needs a ; before it and a , after it. Better yet, use "for example" instead of "e.g." because nearly everyone confuses e.g. and i.e. and I can't tell you how many patches I've made and/or committed in the documentation of Drupal to fix this confusion.

And once we figure out how we're referring to "entities", some more rewriting will be needed of course.

Thanks! A few updates I think are needed:

a) Can we make the link to the online docs follow our standard format? http://drupal.org/node/632280

b) The code indentation is not correct in this patch.

c) The word "text" as in "link texts" should not be plural.

d) In the "Using link texts" [sic] section, some of the instructions seem to be referring to the field settings forms and some to the display forms. I think it's pretty confusing. This applies to most of the other Uses sections too... Just saying "click on the cog icon" is not good enough, because they aren't on the Manage Display page to begin with, they're reading this help page.

Good question about how to refer to things... The Field UI help should ideally tell us in general how to edit field settings and display settings, and hopefully make that distinction. So maybe in individual field modules, after the heading you already have there about field and display settings (the first item in Uses), we can do something like this:

Adding link text

Link text can be set to optional or required in any link field.

Displaying links

There are display settings options for displaying the URL as plain text, the URL as a link, the URL with the supplied link text, and other options.

...

Thoughts? It seems like that would be much simpler.

Actually, I think just saying "this is a field setting" or "this is a display setting" is both simpler and clearer, and that's the main objective for documentation. :)

So maybe if we adopt this format, we should also change the standard heading for the first uses bullet point to:

Field and display settings

?

And then the Link Text thing should maybe read:

There is a field setting that lets you set link text to be optional or required in any link field.

We should refer to the "Field management tab" as follows:

the Manage fields tab

or maybe even simpeler:

the Manage fields page

The part in italics should be something the user can find literally on the page.

I think that is how we have always done, although I have not much evidence to back this up. But in the hook_help for the image module it says:

To add an image field to a content type, go to the content type's manage fields page, and add a new field of type Image.

I completely agree with #27.

Patch:

- fixes comments from #27, #26
- fixes links according to new standard https://drupal.org/node/632280#url-note

Change status

I think this is looking very good!

I only have a few small suggestions:

a) In the "Displaying link text" item in Uses, I think it should say ... choose Link as **the** format... ("the" is missing there).

b) I also think the beginning of that item could use a bit of work: "By default, link text is displayed instead of the URL."... By default, a link field is displayed as a link to the URL with the entered text as the link text, right? So both the URL and the entered link text are used to format the link. The text as it is made me scratch my head to figure out what it meant.

c) In the last Uses item, I think you should use the term "scheme" in the first part where you say only http and https are supported, and not suddenly introduce it in the last part. Not everyone will know what it means, and the extra context will make it clear.

Looking really good! I think this is all very clear and it reads very well.

There are just a couple of typographical/grammatical things to fix now:

a) "In the field settings you can define a link text to be optional..." -- I don't think "link text" is a countable noun. I would suggest "the link text" instead of "a link text".

b) "t(' If link text has been submitted for a URL..." -- there is an extra space at the beginning between ' and If

c) "Links need to start with either with the scheme name " -- two "with"s there.

Looks good to me!

Someone needs to give this some manual testing:
- Make sure the text in the help matches the text in the Drupal user interface
- Make sure all the links work correctly

The patch was tested successfully, all text match and the links are working.

Check the attached image.

#37: link-help-text-2028799-37.patch queued for re-testing.

Retested it as a second test during the drupal mentoring sprint. I can confirm -enzo-'s statement. The text matches and and the urls lead to the right pages.

Retested it as a second test during the drupal mentoring sprint. I can confirm -enzo-'s statement. The text matches and and the urls lead to the right pages.

duplicate

Committed ba6cdc2 and pushed to 8.x. Thanks!