Proposal for "See also" section guidelines

[dipikabh]

Current state of the See also section

The "See also" section across our reference and guide pages are not all that consistent.

• In the Learn area, the links in the "See also" section are documented in the definition list format.
• On other pages, the links in the "See also" section are presented in a bulleted list. Some links, however, are accompanied with a descriptive text about the target page and some are not. These descriptive texts are sometimes phrases and sometimes complete sentences with different surrounding punctuation (colon or em dash). The ending punctuation in the list items is also inconsistent across pages.
• There are mismatches wrt casing in the link text and the target page/section.
• Where the list contains both internal and external links, the order is not consistent across pages.

After looking around at other technical docs and style guides, I have proposed some guidelines here for the "See also" section on MDN.

After there is a consensus, I can add these guidelines to the writing style guide as well as add examples to the template pages. The See also section in the Writing style guide itself uses subsections to list references. This section would need also to be fixed to comply with the guidelines we settle on here.

We can start following these guidelines in the newer pages we write and fix existing pages only as and when we get the chance while making other updates.

Proposal for the guidelines on MDN

UPDATE (23 MAR): PLEASE CHECK THE PULL REQUEST FOR THE LATEST VERSION. These guidelines have changed slightly after further conversations in the pull request.

Here’s a proposal for the guidelines for the “See also” sections on MDN. I have included examples later to illustrate these guidelines. All the Learn entry points for CSS, HTML, JavaScript, and so on follow a definition list format in the “See also” section (one example shown below). We can keep using this format but only for the Learn area.

Link text

• The link text itself should be the same as the title of the page or the section being linked to. (e.g., import layer). (Example 1)
• [UPDATED] Follow the feature name with the appropriate word such as property, function, expression. The link will span the entire link text, including the adjective. (Example 3)
• Add code formatting to the keyword in the link text.
• Follow sentence casing in link text even if it is different from the linked page or section. (it might be that the casing on the page or section is incorrect.) (Example 1)
• For external links as well, use sentence casing even if the casing on the target page is different. This is to ensure consistency on MDN.
• [ADDED] For external links, add the source website as part of the link text. (Example 1, Example 6)
• No article (“A”, “An”, “The”) is needed at the beginning in the link text. (Example 3)
• No punctuation is required after the link text because they will invariably be phrases.

Descriptive text

• Drop all descriptive text surrounding the link. (If we do it for one, we’d have to add a descriptive text for all links. Plenty of tech docs, such as Microsoft and Red Hat, only list the links without any surrounding text in their “See also” sections.)
• If the links can be grouped by a theme, add a lead-in sentence to describe the list of links. End the lead-in sentence with a colon.
• A single item in a list can be a series of comma-separated links, in which case, a lead-in phrase can be added, ending in a colon. Don’t use the conjunction ‘and’ before the last item in the series.
• [ADDED] After an external link, mention the date or year when the article was published within parentheses. Specify date using the format (Month date, year). The publication date not only helps to inform the readers about the relevance of the linked content but also helps authors to review links that are very old. (Example 6)

Order of links

• List the links to reference pages first and then the links to the related conceptual pages.
• If the list is a mix of internal and external links, list the internal links first and then the external ones.
• Follow alphabetical or simple-to-advanced concept order within each group of internal and external links.

[dipikabh]

UPDATE (23 MAR): PLEASE CHECK THE PULL REQUESTS FOR THE LATEST VERSIONS OF THE GUIDELINES AND EXAMPLES.

• Example 1: WAI-ARIA basics - Learn web development
• Example 2: <input type="checkbox"> - HTML
• Example 3: @layer - CSS
• Example 4: revert-layer - CSS
• Example 5: accent-color - CSS
• Example 6: await - JavaScript
• Example 7: Learn landing pages

Note for all lists here as per new guidelines: Unable to show here but the external link arrow icon will be rendered on MDN for all external links. Also, ignore the break in link appearing after the code-formatted text - this is markdown on GitHub.

Example 1

WAI-ARIA basics - Learn web development

As per new guidelines, this would be:

• ARIA states and properties
• WAI-ARIA roles
• Deque University ARIA examples
• WAI-ARIA authoring practices on W3C
• ARIA in HTML on W3C

Here’s an explanation for each of the list items:

• ARIA states and properties
  (This is the second item in the list. The link text should match the page or a section title. Moved up in the list for alphabetical order among the internal links. Descriptive text has been dropped.)
• WAI-ARIA roles
  (This is the first item in the list. The link text should match the page or a section title, the link text should follow sentence casing even if the page title currently is not in sentence case. Ideally, this should not be part of “See also” because it already appears in the article.)
• ARIA in HTML on W3C
  (This is the last item in the list. Moved up in the list for alphabetical order among the external links.)
• Deque University ARIA examples
  (This is the third item in the list. ‘U’ should be upper case and this link text matches a section title on the target page, which also describes the context.)
• WAI-ARIA authoring practices on W3C
  (sentence casing in link text even though not on w3c)

---

Example 2

<input type="checkbox"> - HTML

As per new guidelines, this would be:

• CSS selectors to style checkboxes: :checked pseudo-class, :indeterminate CSS pseudo-class
• HTMLInputElement interface
• <input> HTML element
• CSS property compatibility table for form controls

---

Example 3

@layer - CSS

As per new guidelines, this would be:

• @import at-rule
• !important keyword
• revert-layer keyword
• Introducing the CSS cascade
• Cascade, specificity, and inheritance
• Cascade layers
• The future of CSS: Cascade layers on bram.us (September 15, 2021)
  (links to reference pages, followed by links to conceptual pages, followed by external links)

---

Example 4

revert-layer - CSS

As per new guidelines, this would be:

• all property
• inherit keyword
• initial keyword
• revert keyword
• unset keyword

---

Example 5

accent-color - CSS

As per new guidelines, this would be:

• Other color-related properties: background-color, border-color, color, caret-color, column-rule-color, outline-color, text-decoration-color, text-emphasis-color, text-shadow
• <color> data type
• <input> HTML element
• Applying color to HTML elements using CSS

---

Example 6

await - JavaScript

As per new guidelines, this would be:

• async function declaration
• async function expression
• AsyncFunction object
• Top-level await on v8.dev (October 8, 2019)
  (link should span entire text)

---

Example 7

The Learn entry points for CSS, HTML, JavaScript (screenshot below), MathML, Web performance, and Server-side website programming follow a definition list format in the “See also” section (one example shown below). We can keep using this format but only for the Learn area.

The ‘See also’ in the following Learn area landing pages is a bulleted list and we might want to change them to a definition list format: Accessibility, Getting started with the web, Web forms

[dipikabh]

A concern was raised about the use of “See” in “See also” because the word is unfair to the visually challenged. Here’s what I found:

• As per Google developer documentation style guide:
  • “Use see to refer to links and cross-references” (source)
  • ""see": OK as a general term and when referring to links and cross-references. Our research indicates that language relating to sight is OK for a wide range of readers." (source)
• In Microsoft’s style guide for reference documentation:
  • “See also” is cited as one of the elements of a reference article (source) and described as “References or links to more information about how to use the element. References or links to related elements.”
• PostgreSQL docs also use and prescribe “See also”.

It is okay to retain the section title “See also” on MDN because it is commonly used in other reference docs and widely accepted.

[estelle]

Great work!

With Example #5, I think a paragraph full of links is difficult to read and challenging to click on. I would argue for sub-lists when a bullet list has more than 3 to 5 links, or some similar rule.

With external links, I would like to see the year of publication follow the link. This way our readers and writers get a sense of the relevance of the associated content.

I do think we should list the type of content a link is. We have property, keyword, function, which is great. yes. keep. But we also need something similar for guides, learn, landing page. Not those words per see, but as most links within a see also are on the same or very similar topic, they're going to have similar titles. being able to determine which is the most appropriate link for your needs is good user experience.

[dipikabh]

Thanks for the feedback, Estelle!

With Example #5, I think a paragraph full of links is difficult to read and challenging to click on. I would argue for sub-lists when a bullet list has more than 3 to 5 links, or some similar rule.

Actually I would do the opposite :), that is, if one of the items in a list has multiple subitems (more than three), I would not break it up into bulleted items of a nested list, just to keep the length of the parent list short. If, however, this is the only item in the list with subitems, then sure they can be represented as individual bulleted items. I could not find any list-related rule around this, so I guess it comes down to a matter of preference.

With external links, I would like to see the year of publication follow the link. This way our readers and writers get a sense of the relevance of the associated content.

Yes, you've brought this up before and I think it would be nice to set this as a guideline now. Something like this?

Top-level await on v8.dev (October 8, 2019)

But we also need something similar for guides, learn, landing page.

That is a very good point - to indicate to the reader in some way the area of MDN the link will take them to. So something like the following would be nice:

• Guide: Applying color to HTML elements using CSS

Only problem is that in this particular case, that guide is not available from the list of "Guides" in the sidebar. And also the CSS file hierarchy is relatively flat right now. But even then, I think it will help prefixing links with that kind of information.

[schalkneethling]

Yes, you've brought this up before and I think it would be nice to set this as a guideline now. Something like this?

Top-level await on v8.dev (October 8, 2019)

I really like this idea. 👍

[dipikabh]

@estelle I added a rule under the "Descriptive text" section about indicating the date for an external linked article. Also updated Example 6 to illustrate it.

Regarding your point about somehow indicating whether a link is in learn, guide, etc. I was looking at this link CSS property compatibility table for form controls as an example used in Example 2. The problem with qualifying that as either a "Guide" or "Learn" is that the URL contains "Learn" but the breadcrumb contains "Guides" and so using either can be confusing. I'll leave this for later when we have sorted out the info architecture.

[Josh-Cena]

Nit: in example 6, the first bullet would be "async function statement". Otherwise, looks great to me :)

I do have one problem, though: by adding extra text, link formatting becomes infinitely harder. I can no longer create ad-hoc links by using xref macros. I wonder how useful it is compare to present and future authoring efforts.

[dipikabh]

That is a correct nit! :)

Addressing your second feedback with the next comment as @teoli2003 has also brought it up.

[teoli2003]

I also agree that this is great work.

Nevertheless, we should modify this rule:

Add an adjective such as property, function, expression, … to the link text even if the page title does not have it. The link will span the entire link text, including the adjective.

I agree that we should use the feature type as an epithet of the property, function, or expression, but the link should only span the noun used as an epithet.

E.g., instead of:

• myfunction function

We will have:

• myfunction function

(Remember that, unlike in GitHub, links on MDN are underlined – and that's good. But this makes a long link more difficult to read)

Reasons:

• it stresses the feature name by making it stand out and be more readable.
• it avoids the possible confusion that the link will explain what a property, function, expression, … is.
• it still allows using the link macros ({{cssxref}}), {{domxref}}, … (If not, we may want to get rid of them altogether: forcing editors to learn two ways to do the same thing is not efficient)

Side note: even if we keep this rule, we need to rephrase it as these are not adjectives; they are nouns, as are the feature names before them. The feature names are nouns used as adjectives modifying the noun (not the opposite, as the proposed rule states incorrectly).

[dipikabh]

Thanks for the feedback, Jean-Yves!

I came across this accessibility rule for screen readers that recommends to increase the span of the link to the entire meaningful text. That's why I included the bit about "The link will span the entire link text, including the adjective."

But I see the point both Josh and you make about the hurdle it will cause in authoring since we use macros to create links. I should have preempted it. I agree, we can drop the part "The link will span the entire link text, including the adjective.".

[dipikabh]

I've updated the rule and examples @teoli2003. I'll open a PR shortly to reflect these update these guidelines in our style guide.

[dipikabh]

Pull request to implement the changes as discussed: mdn/content#25191

[dipikabh]

Please check the pull requests for the latest versions of the guidelines and examples.