Sprints: Deal with the {{page}} macro in en-US JavaScript documentation

[wbamberg]

In https://github.com/mdn/sprints/issues/2520 we're trying to decide what to do with all the KumaScript macro calls in our JavaScript documentation.

Mostly we should be able to make a single choice about each macro, but as noted in https://github.com/mdn/sprints/issues/2520#issuecomment-582067362, the {{page}} macro is a bit of a chameleon.

Florian has already removed a lot of these uses in https://github.com/mdn/sprints/issues/2571, but there are 48 left.

So this user story is to decide what to do about all the remaining uses of this macro in the en-US JS documentation.

Acceptance criteria

• either no more uses of the {{page}} macro in the en-US JS docs, or any remaining uses are accounted for as part of "replace" triage (meaning, we have an explicit plan for dealing with them in the scraping step).

[Elchi3]

A lot of the Intl pages still use {{page}}, so I think this task will also include the work in https://github.com/mdn/sprints/issues/2537. Once we've done that, we can add constructor pages, remove prototype pages, and any additional {{page}} usages.

[Elchi3]

Here's what left of {{page}}

Random pages with page macro calls:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

Intl related page macro calls:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toLocaleString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/toLocaleString

[Elchi3]

This is now done except two pages:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

The Cheatsheet is relatively new, I don't know what to do about this.

The reference seems to be duplicating a lot of info from the listings on the Standard build objects, Statements, and Operators reference listing pages and I wonder if I want to re-do this page to look like a much better overview using the tiles that I've used on https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide

Thoughts?

[wbamberg]

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

This one is a landing page, and {{page}} is being used more or less to assemble lists of links to put in it. We would like to have a consistent way to create and render landing pages, rather than it being a free-for-all.

In "structured markdown" we have a definition of a landing page already. One thing we have to do for the JS docs, is work out, for all the landing pages, how we would scrape them into structured markdown and what kinds of upstream changes would be needed to make them scrapable (aka stumptown-compatible).

Some landing pages look quite easily scrapable (e.g. https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors, which basically consists of some prose followed by a ListSubpages macro call. ListSubpages maps quite cleanly onto the stumptown "link list" thing.

So what I'd suggest for this page is:

• decide how we want this page to look
• if we can build a page like that in a way that's compatible with the landing page recipe, (e.g. replace page calls with ListSubpages calls) then do that.
• if we can't, because the landing page recipe and associated primitives are not powerful enough, consider whether we want to extend the way we want to represent landing pages as structured markdown, so we can meet the needs of this page. For example, supporting tags and letting link lists filter by tags.

---

I would also say, I'm never very keen on documentation that imposes a lot of taxonomy on readers, since taxonomy tends to get subjective or make demands on readers. For example, what does "fundamental object" really mean? Why isn't Number a fundamental object? What does "structured data" mean as a category? What value are these categories giving to users?

[wbamberg]

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet

This one is difficult. As you say it is new, and it's a useful page, and transclusion is the best way to do this :(. Now the regex docs are split into separate pages, having a one-page cheatsheet seems really useful.

Perhaps keep this page (maybe renamed to "Regular expression syntax" or something), and have the pages on the particular categories (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions) link to the relevant section of this page?

@SphinxKnight , any views on this?

[SphinxKnight]

As said earlier, this is pretty recent.
I'm not really keen of removing content from detailed pages and link to this page (after all having the "syntax" is part of the "recipe" of other pages in the JS Ref).

All in all, for a single page, I consider the cost of duplicating such tables in this cheatsheet (and maintaining them here) is lower than the costs of other solution.
Give me a go and I'll take care of that.

P.S. For the Reference page, I concur with what has been said before, having a "JS Guide"-like/landing page would be far better :)

[Elchi3]

Perhaps keep this page (maybe renamed to "Regular expression syntax" or something), and have the pages on the particular categories (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions) link to the relevant section of this page?

This could work indeed.

All in all, for a single page, I consider the cost of duplicating such tables in this cheatsheet (and maintaining them here) is lower than the costs of other solution.
Give me a go and I'll take care of that.

I also agree to this and I'm not sure I have a preference right now. I think we should just try one option and see how it feels. @SphinxKnight do you want to give this a try and report back?

[SphinxKnight]

I went with duplicating content in the cheatsheet and added a <div class="hidden">Please do not forget to edit this page as well. Thanks!</div> in the different pages (incl. the cheatsheet)

Only 1 remains:

• [ ] https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference
  ☠️

[Elchi3]

Thank you @SphinxKnight :+1: I guess that could work.

For the reference page, I went ahead with what I meant earlier: It now looks like the Guide landing page: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference

What do you think, Will?

[wbamberg]

What do you think, Will?

As far as the scope of this bug is "what shall we do about calls to {{page}}" - people of course use {{page}}, as well as things like {{ListSubPages}} and (stumptown "directory link lists") to help maintenance, because the source only lives in one place. One option for removing these macros is always to duplicate the content.

So from that narrow perspective, that's the solution chosen here. It has the disadvantage that when more items are added this has to be updated, and the advantage that there's no clever stuff to worry about.

As far as "stumptown-compatible" is concerned, this solution has the problem that it uses custom styling via CSS classes, so we can't represent it using plain Markdown prose. We could implement something like this if we represented the collections of links using a link list, then said to the renderer "the correct way to render a link list is as a card grid". But then every link list gets rendered like this, and we have to decide if that's appropriate.

In general it's helpful I think to try to separate the way we author the content from how we would like it rendered, and that's one of the things stumptown tries to achieve. That's why we invent things like link lists rather than using blobs of Markdown.

So: how would we author a solution like this in structured Markdown? As plain prose or using some abstract structure like a link list?

I think one limitation about this particular option is that it doesn't show short descriptions, which I think can be very helpful in landing pages, where the page title alone doesn't always give you enough information about what the thing is. In general though, I care less about specific choices about how landing pages are rendered (like, are they a table, or a ul, or a dl, or a grid, do they show short descriptions...) than that they are all authored and rendered consistently, and that the authoring interface is relatively simple and understandable.

[Elchi3]

So: how would we author a solution like this in structured Markdown? As plain prose or using some abstract structure like a link list?

Good question, at this point I'm not sure if we need a structure for this page, but as it is used both on the overview for the JS guide and now here (and I also think it would be nice for the header list), it seems like this kind of structure "high level landing page" is a common pattern.

I think one limitation about this particular option is that it doesn't show short descriptions, which I think can be very helpful in landing pages, where the page title alone doesn't always give you enough information about what the thing is.

I think it would be a good idea to think about "lists without short description" as a thing that stumptown could do and then have the renderer render out the tiles or something else that looks nice.

I agree to be consistent when authoring and rendering content. This pattern (high level landing page without short description) I've only seen now and I'm not sure what everyone else thinks about it or whether we need this page type. I think I would like to continue that conversation later when we have dealt with more content and this comes up again (and if it doesn't, find a different solution than a new content type).
If you like, I can capture this in a new issue, but I would like to close this one now.

[wbamberg]

OK, let's close this. We should have a separate story for "dealing with the JS landing pages" and we can look at this then.

[Elchi3]

Thank you, Will! :)