docs(meta): Add See also section guidelines to writing style guide

[dipikabh]

Motivation

This discussion describes the existing inconsistencies across the See also sections and the proposed set of guidelines to follow from here on.

Details of changes

• In the Writing style guide:

1. With the non-implementation of exposing H3 headings in the page TOC on the right, added a mini TOC in each of the three H2 sections "General writing guidelines", "Writing style", and "Page components".
2. Upgraded "Shortened URLs (shortlinks)" from H4 to H3 and also edited the section a bit.
3. Added the "See also section" section per the proposal in the discussion.
4. Updated the "See also" section of the Writing style guide to comply with the new guidelines.

• In the template files:
  Updated the "See also" section to refer to the guidelines in the writing style guide.

TO DO

• Organize sub-sections in the writing style guide in alphabetical order.
• Update "See also" sections in the pages used as examples in the discussion: docs(fix): Apply See also guidelines as examples #25380

[github-actions]

Preview URLs (15 pages)

• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_constructor_subpage_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_event_subpage_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_method_subpage_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_property_subpage_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_reference_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/ARIA_Page_Template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_property_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_selector_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Glossary_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/SVG_element_page_template
• /en-US/docs/MDN/Writing_guidelines/Writing_style_guide
• /en-US/docs/Web/CSS/@layer

Flaws (43)

Note! 3 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/MDN/Writing_guidelines/Writing_style_guide
Title: Writing style guide
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Web/JavaScript/Guide/Details_of_the_Object_Model

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_event_subpage_template
Title: API event subpage template
Flaw count: 3

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
• broken_links:
  • Can't resolve /en-US/docs/Web/API/Window/animationcancel_event
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheEvent_event

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_method_subpage_template
Title: API method subpage template
Flaw count: 2

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheMethod

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template
Title: HTML element page template
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheElement

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/ARIA_Page_Template
Title: ARIA page template
Flaw count: 1

• macros:
  • `/home/runner/work/content/content/node_modules/@mdn/yari/kumascript/macros/Specifications.ejs:1

1| <%
2| /*
3| Placeholder to render a specification section with spec_urls from BCD
4|

No first query argument or 'browser-compat' or 'spec-urls' front-matter value passed`

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template
Title: HTTP header page template
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheHeader

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template
Title: API landing page template
Flaw count: 10

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
  • /en-US/docs/Web/API/NameOfTheInterface does not exist
  • /en-US/docs/Web/API/Addition1 does not exist
  • /en-US/docs/Web/API/Addition1 does not exist
  • Calling the Specifications macro with any arguments is deprecated; instead use either the 'browser-compat' or 'spec-urls' front-matter key.
  • and 3 more flaws omitted
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.Interface_1
  • No BCD data for query: path.to.feature.Interface_2

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_selector_page_template
Title: CSS selector page template
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: css.selectors.NameOfTheSelector

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_constructor_subpage_template
Title: API constructor subpage template
Flaw count: 3

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
  • /en-US/docs/Web/API/NameOfTheParentInterface does not exist
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheConstructor

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_reference_page_template
Title: API reference page template
Flaw count: 16

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
  • /en-US/docs/Web/API/NameOfTheInterface/NameOfTheInterface does not exist
  • /en-US/docs/Web/API/NameOfTheInterface does not exist
  • /en-US/docs/Web/API/NameOfParentInterface does not exist
  • /en-US/docs/Web/API/NameOfTheInterface/staticProperty1 does not exist
  • and 10 more flaws omitted
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheInterface

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/SVG_element_page_template
Title: SVG element page template
Flaw count: 2

• macros:
  • /en-US/docs/Web/API/NameOfSVGDOMElement does not exist
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheElement

---

URL: /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_property_subpage_template
Title: API property subpage template
Flaw count: 2

• macros:
  • /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheProperty

External URLs (11)

URL: /en-US/docs/MDN/Writing_guidelines/Writing_style_guide
Title: Writing style guide

• https://brians.wsu.edu/common-errors-in-english-usage/ (1 time) (Note! This may be a new URL 👀)
• https://docs.microsoft.com/style-guide/welcome/ (1 time) (Note! This may be a new URL 👀)
• https://english.stackexchange.com/ (1 time) (Note! This may be a new URL 👀)
• https://v8.dev/features/top-level-await (2 times) (Note! This may be a new URL 👀)
• https://www-personal.umich.edu/~jlawler/aue.html (1 time) (Note! This may be a new URL 👀)
• https://www.chicagomanualofstyle.org (1 time) (Note! This may be a new URL 👀)
• https://www.dictionary.com/ (2 times) (Note! This may be a new URL 👀)
• https://www.google.ca/books/edition/Style/QjskvgEACAAJ (1 time) (Note! This may be a new URL 👀)
• https://www.google.com/books/edition/Merriam_Webster_s_Dictionary_of_English/UDIjAQAAIAAJ (1 time) (Note! This may be a new URL 👀)
• https://www.harpercollins.com/products/on-writing-well-william-zinsser (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/CSS/@layer
Title: @layer

• https://www.bram.us/2021/09/15/the-future-of-css-cascade-layers-css-at-layer/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-03-22 19:46:36)

[Josh-Cena]

This list still doesn't follow the new See also guide (which says titles-only), does it? ^^ I slightly prefer the original style (without a list), and I would rather change the title to "Further reading" if "See also" implies some kind of structure.

[dipikabh]

Yeah, you're right. This "See also" section in the writing style guide is still description-heavy and kinda non-compliant with the proposed guidelines. So, good catch! I guess I missed to make it titles-only in trying to first convert the subsections into a bulleted list. But before I fix that now, I would need clarifications about your other comments:

I slightly prefer the original style (without a list)

Did you mean in this particular case or in general for the "See also" sections elsewhere?

I would rather change the title to "Further reading" if "See also" implies some kind of structure.

Is this specific to content in this section or in general?

Are you saying that you'd like to keep the See also section in the writing style guide as is but rename the heading to "Further reading"?

The "See also" section in the style guide should be able to exemplify the guidelines recommended in the style guide. So it would be nice to make it a bulleted list of links and retain the title.

[Josh-Cena]

Yes, my comment specifically refers to this page's See also—I agree with the guideline. I think the previous prose-like content is easy to read and also contains useful information, so making it a bulleted list seems like a net loss, apart from exemplification purposes.

[dipikabh]

Thanks, I see your point. I've updated the section title in this case to "Further reading".

Retaining the existing descriptive info for links and not getting rid of all of it is, in general, good advice. So now there is a guideline on how to retain that info, wherever it may already exist. Please see comment below.

[teoli2003]

Approving = expression of my agreement on the new rules (But we want to wait for other reviewers' expression of approval before merging)

[dipikabh]

Thank you, @teoli2003!

[hamishwillee]

I'm going to be the minority, but I prefer "succinct where possible". Consider @layer linked here - as a reader and a writer, import tells me enough, while to me the fact that !important is a flag seems a little unnecessary. I mean if I know what it is then I know its a flag, and if I don't then having that information won't change my desire to click or not click it.

Phrases where they tell you something useful are excellent, but fewer words is better.

[hamishwillee]

PS, and this does not match the guide. The see also section here says use bulleted list, but bulleted list says that we use bulleted list with phrase and punctuation. Here we have no punctuation.

Upshot, we should fix the example of "how to do it right" so that it does it right :-)

[dipikabh]

Thanks for the feedback, Hamish.

• I've actually incorporated this now (I agree). I've removed the guideline about adding a descriptor for the keyword. :)

• I've added an updated version of this @layer example to clarify what it would look like (though I've yet to update all other examples demo'ed in the discussion.). It is also the example we're linking to in the style guide in the "See also" guideline section.

• Also, I've updated the "bulleted list" guideline in the style guide. Only complete sentences end in period. If the list item is a phrase, it will not end in a period, which is what the above @layer "See also" is following (6af59ab)

[hamishwillee]

@dipikabh I like what you've done in #25191 (comment)

I'm a little concerned with the use of the term "phrase" -it has many definitions, and a phrase can be a sentence.
Consider using the terms "single word", "incomplete sentence" and/or "topic title" or similar (i.e. a topic title might be a complete sentence, but normally we won't want to put a full stop after it - though it does not harm.

FWIW My preference (when I control the rules an open source doc set):

1. If it is a sentence, capitalize the first letter
2. No full stops by default - for either a sentence or a partial sentence.
3. Try avoid multiple sentences in bullet points. But if there are multiple sentences, these should be fully punctuated, including the final sentence.

This ensures that in the majority of cases there are no full stops, which is more consistent, and looks better in cases when you have lists with mixed sentences and partial sentences. The purist in me says use full punctuation everywhere, but this does not look as good, and is annoying to enforce when no one does so any more. Just my two bits.

[dipikabh]

A phrase is never a complete sentence. Nevertheless, I've added a clarification for the term in "Bulleted lists" in the "Lists" section.

I agree with point 3. Some of this is already documented in "Bulleted lists". I've additionally added the following (borrowed from microsoft's guideline):

If one or more list items are complete sentences, use a period after every list item, even if a list item contains three or fewer words.

Point 2 - A sentence would always need to end in a period. The above rule will help if there is a mix of complete and incomplete sentences. And we're also emphasizing to follow the same sentence structure across all list items.

Updates are in b178e10. Let me know what you think @hamishwillee.

[hamishwillee]

Thanks @dipikabh - I've noted the only "annoyance" here b178e10#r104453682

But looks fine to me! Thanks.

[dipikabh]

Thanks for sharing, @hamishwillee. I hope the response answers your concern.

I'll be opening another PR to address some of the examples I had brought up in the original discussion. We can tweak/clarify the guidelines further, if needed, as we go along.

[hamishwillee]

Despite my comment https://github.com/mdn/content/pull/25191/files#r1133465543 , this is a heap better and more consistent. Approving.

[dipikabh]

After feedback from @Josh-Cena and @hamishwillee (I agree with both the comments), here's a slight tweak to the original proposal:
/cc @teoli2003

• In case of links to reference pages, let's drop the descriptor such as keyword or property (commit)
• In cases where there is already descriptive text, let's not remove it all. Some of it is good information. Instead, added a guideline on how to present that descriptive info:
  • <link text>: description phrase(no punctuation)

• Keep the descriptive text surrounding the link minimal. In case of a description, add it after the link text and a colon. Word the description as a phrase with no ending punctuation. Keep all linked text at the beginning to aid in scanning the list of links.
• Correct: :checked", :indeterminate: CSS selectors for styling checkboxes

[dipikabh]

Thanks. @bsmth. I've incorporated your feedback (9120313)

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.

[bsmth]

Thanks, @dipikabh - no other comments for me after you resolved the outdated ones. Thanks for the lift! 🎉

[Josh-Cena]

The text looks alright to me, but its implications as manifested in the examples (#25380 (comment)) worry me. So I'd like to discuss over the examples and get them merged before approving this one. In particular, any non-structured description text is going to make the list much harder to maintain and keep consistent across related pages.

[dipikabh]

Thank you all for your feedback and the brainstorming to iron out the guidelines for "See also". The main points in the style guide can be viewed here: See also guidelines. @hamishwillee rightly pointed out what we say in the bulleted lists section should be in sync with the lists in "See also" and that's been clarified as well, hopefully.

It would be good to land this soon so we can start using the guidelines 🙂.
cc: @Josh-Cena @hamishwillee @teoli2003

[Josh-Cena]

LGTM. Thanks for the work!

[Josh-Cena]

Is there an example for this?

[dipikabh]

This needed to be removed because of the updated guideline just before it. (1e8d353)

[dipikabh]

Thanks for the approvals and support, everyone. Merging this now.

As always, if there are still any points we want to clarify further or feel the need to add to guidelines, especially after we start complying with the guidelines (there might be more varied instances in the existing "See also" sections), we can do so in subsequent follow-up PRs.

[Josh-Cena]

@dipikabh I was trying to apply the guideline on external see also links. I have several questions:

• Should we consistently include the author and source of the article?
• If we are quoting a chapter from a book or a section from a post, should the link text be the chapter/section title itself or something like "Section X from XYZ, by Aaaa (January 1, 1970)"?
• Should a live-updated book in a GitHub repo get a date?

It may help to give a few more examples on external links. For example, here are a few I attempted:

• JavaScript Data Structures and Algorithms by Oleksii Trekhleb
• Event loops in the HTML standard
• The Node.js Event Loop, Timers, and process.nextTick() in the Node.js documentation
• JavaScript modules on v8.dev by Addy Osmani and Mathias Bynens (June 18, 2018)
• ES modules: A cartoon deep-dive on Mozilla Hacks by Lin Clark (March 28, 2018)
• ES6 in Depth: Modules on Mozilla Hacks by Jason Orendorff (August 14, 2015)
• Chapter 16: Modules from Exploring ES6 by Axel Rauschmayer

[hamishwillee]

...

• Should we consistently include the author and source of the article?

These are all good questions, for which I believe we have no rules yet.

FWIW I would normally do a list like the one above as follows:

• JavaScript Data Structures and Algorithms (github.com/trekhleb)
• Event loops in the HTML standard
• The Node.js Event Loop, Timers, and process.nextTick() in the Node.js documentation
• JavaScript modules (v8.dev)
• ES modules: A cartoon deep-dive (hacks.mozilla.org)
• ES6 in Depth: Modules (hacks.mozilla.org)
• Exploring ES6, Chapter 16: Modules by Axel Rauschmayer

Why?

• For blogs dev sites, the site url tells you the "value" if you know the site - the author does not usually tell me anything extra to help me know if the link is likely to be useful.
• For a book, I think it is good manners to do the book name and author - for a well know book the author matters.
• Naming the spec is sufficient, but generally on MDN we try avoid direct linking to spec sections for documentation.
• Not so sure on dates. In theory they are useful for noting that content is "old", but it depresses me to see a whole set of links with old dates, but still doesn't tell me that they are good or not.

All that said, I do not feel strongly about this. It just appeals to my minimalist tendencies.