[Glossary] Links guidelines

[klez]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi all
Sorry I wasn't able to attend Monday's meeting but, as I said, I had
stuff to do at our data center :/

Anyways, I read part of the discussion revolved around the format of
the links in the Learn More section of the Glossary entries. Here are
my two cents:

* When the entry is about a project (e.g. WebKit)
* <a href="http://....">WebKit official page</a>
or similar wording but same structure, that is, whole phrase as a link

* When we are linking to an external reference (Wikipedia, OWASP, etc.)
* <a href="http://.....">WebKit</a> on Wikipedia
which is consistent with what we have done so far

* When the link is internal to MDN (e.g., the Hyperlink entry has
links to the <a> and <link> elements reference)... I have to admit I'm
a little bit torn about this. In the given example I see
* <a href="http://...">&lt;a&gt; on MDN</a>
which may be good. But I'd prefer something like
* <a href="http://...">&lt;a&gt; reference</a>
where "reference" can be substituted with "tutorial" or "guide" as needed.

These, as I said, are my 2 cents. I'd like to have a bit of discussion
around this so, when we reach a consensus, I can update the guidelines
so that it will be clearer to new (and existing) contributors.

Thank you all
klez
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJV3Mr2AAoJEDN2523zildFKekP/17MtJKt2qJkgCks1mxJR3mL
3/lAx1KZrGB3vKoxQdiEedV2BzkRXKTGcMpDGii5wv0PiVn3+i2PpjvaS9sQdb2h
FxDuDd8ZlIY5xzPhf1bnviT6c50HuwT4je9ED8D77DUWulYkLDrWT9xCtmu1l0HY
jvdyBwslgshMnkuSSaNWoofK8YjoDJ5Ky0AyJAUN4nXLtWrNRiQjeCiZ+aq9IDpR
IorphXnxQXcxxLPt1nFBMr7mVz0AM6wRoGoq94n0SSTL9mmFtKSpJisDqrik4k0P
w+n8z0vG+nT6vdXhh6fCKhL/W/CDa8x4A0H2lpVvo8vOGZiJO+bT6xy7QtZi9jWp
upJL2p8CvHHjrZ9plTHl1kLoWG6Gq/EQ/HPQTLbRG1K5+cn3bXlKff/ypQucNK+w
ryarHbyNVrTX4APnYwXcuEbSFovMbi0BKkSXZ4wwbsCxVMxRyXg3rR/XpXKBbUYZ
cBmhMFSyjhTp0h9wmRHa1QlpqGg/1qCT9AMfAUgq3DsWygETsu5TPQBjtgFE0qed
mo7cFTt3us2UWYqaenfNnOghFLcogO6EcNLHmCx2ASLCSfcrZ+hiYUiZxezx6QZU
GkRkCxHE/hEes4UlsNv45PU2r7E/tgLAjW+oVqTD2dszFdt3zBsP1IBQ0w3DCT45
uEHLhfdKgIyNhtgQOUM8
=DJUr
-----END PGP SIGNATURE-----

[Sebastian Zartner]

>
> * When the entry is about a project (e.g. WebKit)
> * <a href="http://....">WebKit official page</a>
> or similar wording but same structure, that is, whole phrase as a link
>

I agree.

> * When we are linking to an external reference (Wikipedia, OWASP, etc.)
> * <a href="http://.....">WebKit</a> on Wikipedia
> which is consistent with what we have done so far
>

I'd still link the whole phrase. In the example above you are referring to
the Wikipedia page describing WebKit, so 'on Wikipedia should be part of
the link.
Generally I believe the <a> tags should enclose all parts of text referring
to the linked page.

> * When the link is internal to MDN (e.g., the Hyperlink entry has
> links to the <a> and <link> elements reference)... I have to admit I'm
> a little bit torn about this. In the given example I see
> * <a href="http://...">&lt;a&gt; on MDN</a>
> which may be good. But I'd prefer something like
> * <a href="http://...">&lt;a&gt; reference</a>
> where "reference" can be substituted with "tutorial" or "guide" as needed.
>

Related question: Should macros be used instead of HTML tags? E.g. in this
case {{HTMLElement("a")}}.
Personally I don't have a preference, just wanted to throw this question in.

Besides that, I also slightly prefer 'reference' over 'on MDN'.

Sebastian

[Eric Shepherd]

klez wrote:
> * When the entry is about a project (e.g. WebKit)
> * <a href="http://....">WebKit official page</a>
> or similar wording but same structure, that is, whole phrase as a link

Agreed. That is the way it should be done. <a
href="http://external.link">Official WebKit documentation</a> (or
similar; the point is, all text inside the link).

> * When we are linking to an external reference (Wikipedia, OWASP, etc.)
> * <a href="http://.....">WebKit</a> on Wikipedia
> which is consistent with what we have done so far

Here I would amend this slightly:

For links to a definition of a term on another site (such as linking to
the "WebKit" article on MDN, I'd do it just like you do above; the fact
that it's on another site is incidental and not particularly important
to the reader. For instance: "

On the other hand, if the link's purpose is to provide an authoritative
explanation or overview or specification, then including the name of the
destination in the link makes sense to me, as in: "For details, see <a
href='https://www.khronos.org/opengles/sdk/docs/man/xhtml/glLineWidth.xml'><code>glLineWidth()</code>
in the OpenGL ES specification</a>." In this case, making it clear that
the target of the link is authoritative rather than simply a
possibly-interesting page is accomplished by including the name of the
target site.

> * When the link is internal to MDN (e.g., the Hyperlink entry has
> links to the <a> and <link> elements reference)... I have to admit I'm
> a little bit torn about this. In the given example I see
> * <a href="http://...">&lt;a&gt; on MDN</a>
> which may be good. But I'd prefer something like
> * <a href="http://...">&lt;a&gt; reference</a>
> where "reference" can be substituted with "tutorial" or "guide" as needed.

There should never be "on MDN" in links which are internal to MDN. It's
just not necessary. I agree with you entirely here; these links should
always be either simply "<a href='/en-US/docs/Web/HTML'>HTML</a>" or "<a
href='/en-US/docs/Web/HTML/Element'>HTML element reference</a>.

--

Eric Shepherd
Senior Technical Writer
Mozilla <https://www.mozilla.org/>
Blog: http://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Check my Availability <https://freebusy.io/eshe...@mozilla.com>