Support JS sidebar

[wbamberg]

To represent the JS docs in stumptown we need to have an implementation of a sidebar in stumptown that's suitable for the JS docs.

Acceptance criteria

• we have a specification for a JS sidebar in stumptown-content
• we can render this in a web page

[wbamberg]

Notes from Berlin meeting:

---

Currently we have 2 JS sidebars:

One (JSSidebar) on pages like this: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference - that shows all the JS docs (tutorials and reference)
One (JSRef) on pages under built-in objects, like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer - that shows all the properties, methods &c of that object

We should not do this. Instead we should have a single sidebar for all the JS docs, that contains the same detail as the sidebar in (2). When the user is on a particular object page, the sidebar could expand the section of the sidebar containing that object’s methods, properties &c. Like the sidebars in the webextensions docs.

For the content in (1), it seems that existing stumptown sidebar structures (directory lists, chapter lists) would be enough. For the built-in objects section of the sidebar, we’d need to add some logic to stumptown. It would be enough to allow authors to qualify a “directory” listing using a recipe, so they can say: “include all the pages in this directory that are javascript-method pages”. This would be a more constrained alternative to just supporting tags, which we don’t yet support in stumptown.

[wbamberg]

To begin with I'd like us to agree on what a JS sidebar should look like. I've made a mock JS sidebar, more or less following the design above, and put it here: https://wiki.developer.mozilla.org/en-US/docs/User:wbamberg/mock-js-sidebar.

Some things we could say about this sidebar design:

1. it is nice to have a unified presentation of all the docs, that's always the same. For instance if I'm on the page for Array.slice and I want to get to String.slice, it's pretty logical (I think) how to get there, and it's always the same route, no matter where I am.

2. it's massive: 159K of HTML. It compresses to 12K though (transferred size of the page is 38K according to the Network Monitor, compared to 34K for the original https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date). So 🤷.

3. it has too many levels of nesting: 5 at the deepest (Reference>Built-in objects>Array>Properties>Array.length). I think 3 levels is fine. I would probably address this by removing the "Reference" top-level and making it implicit that this is reference documentation. That would get us to 4 levels, which is maybe OK?

4. there are no typographic cues like bold or code styling. I think this does make it harder to scan. Supporting this would be tricky because it tends towards making the author specify presentation rather than just content. I wonder if stumptown could automatically code style links in sidebars that are to any pages except guide or landing pages? That sounds promising.

5. this mockup makes <summary> text linkable. So for instance in "> Array", the "Array" is a link and does something different from clicking the disclosure arrow. That's a change from the old sidebars. It has pros and cons :).

6. the "Built-in objects" section also includes things like "eval()" that I might prefer to put in a category like "Global functions", and not give any child items.

7. I've omitted "prototype" in link names, and the "Inherited" sections from the built-in object sections.

8. links to sibling pages can be way way down the page. For example, suppose we are at a page under WeakSet. The links to the other WeakSet properties will be hard to reach. I think in Berlin we discussed maybe floating the current set of siblings to the top. I think it would be worth mocking this option. I'm not sure how easy it would be to implement in a generic way, and it tends to make the sidebar less unified (the sidebar is different for every object).

[wbamberg]

Here's a version that "floats" the siblings, and also doesn't contain properties for other built-in objects: https://wiki.developer.mozilla.org/en-US/docs/User:wbamberg/mock-js-sidebar2.

This seems better to me actually.

@Elchi3 , @chrisdavidmills , @ddbeck , I'd be happy to hear feedback when you are able.

[Elchi3]

Thanks for giving this a go and making (bold) decisions, Will!

it is nice to have a unified presentation of all the docs, that's always the same. For instance if I'm on the page for Array.slice and I want to get to String.slice, it's pretty logical (I think) how to get there, and it's always the same route, no matter where I am.

Yes. I agree with this 100% and this will be a nice improvement. This was the goal of {{jsSidebar}} originally. Unfortunately, it didn't do that for the reference part of the docs.

it has too many levels of nesting: 5 at the deepest (Reference>Built-in objects>Array>Properties>Array.length). I think 3 levels is fine. I would probably address this by removing the "Reference" top-level and making it implicit that this is reference documentation. That would get us to 4 levels, which is maybe OK?

I agree to remove "Reference" as a workaround if needed, I don't think it is needed necessarily.

there are no typographic cues like bold or code styling. I think this does make it harder to scan. Supporting this would be tricky because it tends towards making the author specify presentation rather than just content. I wonder if stumptown could automatically code style links in sidebars that are to any pages except guide or landing pages? That sounds promising.

Styling according to page type sounds promising indeed, but for JS this falls apart quickly. Some language features are reference pages, but they mostly have English titles instead of code.
What do you think about status icons? (deprecated, non-standard). I guess it falls into the category of inline icons and those we're dropping, too.

this mockup makes <summary> text linkable. So for instance in "> Array", the "Array" is a link and does something different from clicking the disclosure arrow. That's a change from the old sidebars. It has pros and cons :).

I like this! :)

the "Built-in objects" section also includes things like "eval()" that I might prefer to put in a category like "Global functions", and not give any child items.

Yes, I think even the spec calls these things global functions, global properties and global constructors. See also categories here https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects#Standard_objects_by_category

I've omitted "prototype" in link names, and the "Inherited" sections from the built-in object sections.

We talked about omitting "Inherited" sections, so that is fine with me.
On "prototype": this was discussed before at length. See https://discourse.mozilla.org/t/incorrect-titles-for-method-property-articles/31641/ Not sure what we decided or how we will decide.
See also this thread where Bz tries to find an answer for the DevTools console: https://twitter.com/bz_moz/status/1226977763950759938

Here's a version that "floats" the siblings, and also doesn't contain properties for other built-in objects: https://wiki.developer.mozilla.org/en-US/docs/User:wbamberg/mock-js-sidebar2.

This is a neat idea! I think I don't like that it then starts with tutorials again and only then you are back to your reference parent tree, but I don't know how users really travel along with sidebars. Would be interesting to research...
I was thinking about a sidebar that maybe always jumps to the correct position. The Microsoft docs do that. Try to click around here which is nested quite deep: https://docs.microsoft.com/en-us/cli/azure/cdn/custom-domain (also, they make the sidebar scroll, which I think is useful, too [they must have user tested this, I suppose!]).

[chrisdavidmills]

@wbamberg I'm just trying to think whether I've got anything to add here beyond what @Elchi3 has already said.

I don't think not having bold/code on the items is a huge loss. If we could just have code on the reference bits, that would be nice, but let's see how this goes.

I think the second version is definitely better. Simpler, with less nesting levels is definitely better.

It would be nice to see a case that has more than just instance methods (static methods, and instance/static properties too) — how would this work? Should the categories be "Instance methods", "Static methods", etc., just to make that clear?

After you get past the reference stuff for the current Object, the order should be altered so that the other reference stuff is just below it, and then the tutorials at the end. I think that makes more logical sense in this context.

I love that the summary elements are now clickable links, although we should make sure that this only occurs where it makes sense, and just non-clickable text in other cases?

[wbamberg]

Thanks for your thoughtful comments!

Styling according to page type sounds promising indeed, but for JS this falls apart quickly.

You're right of course. That occurred to me too some time after writing this. I think actually we could perhaps address scannability without needing code styling.

On "prototype": this was discussed before at length.

Yeah, sorry, I shouldn't really have brought this up. Since the sidebar just slurps page titles, this emotive question is independent of sidebar design so we don't have to worry about it today. Phew!

I was thinking about a sidebar that maybe always jumps to the correct position. The Microsoft docs do that. Try to click around here which is nested quite deep: https://docs.microsoft.com/en-us/cli/azure/cdn/custom-domain (also, they make the sidebar scroll, which I think is useful, too [they must have user tested this, I suppose!]).

This is very interesting. I had thought my point 8 was a fatal objection to the first proposal, but I like this design a lot. Yes, we'd need scrollable sidebars, but I think we should have that anyway.

(Note that the Azure sidebars don't make <summary> text linkable, and instead the first item after it is the overview link. I don't think I like that, but, just an observation.)

I think the second version is definitely better. Simpler, with less nesting levels is definitely better.

I did like version 2 better, but with Florian's suggestion to do what the MS Azure docs do and scroll to the relevant spot (https://docs.microsoft.com/en-us/cli/azure/cdn/custom-domain?view=azure-cli-latest), I think perhaps I like 1 more. Having the same sidebar on every page seems quite powerful for navigation. Also, I think it'll be easier to implement! I find it hard to think how we could have a single sidebar specification that implements version 2. I know this isn't the greatest reason though. I'll think some more about implementation choices.

It would be nice to see a case that has more than just instance methods (static methods, and instance/static properties too) — how would this work? Should the categories be "Instance methods", "Static methods", etc., just to make that clear?

Yeah, this is a really good point. Actually, for our current sidebars this distinction is made by whether or not the title include .prototype, so of course by omitting that, I've lost the distinction. However, it might be better to make this distinction more explicit:

Date
    Constructor
        Date()
    Static methods
        Date.UTC()
        Date.now()
    Instance methods
        Date.getDate() // or Date.prototype.getDate()
        Date.getDay()  // or Date.prototype.getDay()

I will have a think about how we might implement something like this.

[chrisdavidmills]

I did like version 2 better, but with Florian's suggestion to do what the MS Azure docs do and scroll to the relevant spot (https://docs.microsoft.com/en-us/cli/azure/cdn/custom-domain?view=azure-cli-latest), I think perhaps I like 1 more. Having the same sidebar on every page seems quite powerful for navigation. Also, I think it'll be easier to implement! I find it hard to think how we could have a single sidebar specification that implements version 2. I know this isn't the greatest reason though. I'll think some more about implementation choices.

I think this could be good too - definitely worth protyping out.

Yeah, this is a really good point. Actually, for our current sidebars this distinction is made by whether or not the title include .prototype, so of course by omitting that, I've lost the distinction. However, it might be better to make this distinction more explicit:

Yup, this is the kind of thing I was thinking! Again, worth prototyping out ;-)

[ddbeck]

I don't have much to add here. I think Florian and Chris covered this well. I'm happy with the content of the sidebars and it seems like a reasonable path to a design too.

But because I can't help myself, I wanted to comment on the <summary> as overview link thing. I think it'll require some careful work to make this work for everyone. I found it surprising that clicking the disclosure icon does something different from the text (I'd compare this to a form, where clicking on the text of a checkbox item does something different from the checkbox itself). We can probably make it work, but we'll probably need something like the float or/and scroll too. Clicking the summary might navigate you away from the current page, but it should also expand that part of the tree and make it visible on the subsequent page load.

[wbamberg]

I think it'll require some careful work to make this work for everyone. I found it surprising that clicking the disclosure icon does something different from the text (I'd compare this to a form, where clicking on the text of a checkbox item does something different from the checkbox itself).

Yeah, I do agree here. It is jarring, expecting to open a section of the menu and navigating to a different page, and the analogy to clicking a label is strong. I think that's the reason MDN doesn't do this at the moment, although the alternative is clunky too.

But I hope we will be able to say that this is a presentational thing for the renderer to sort out. If we just provide the content, the renderer could decide whether to include the link in the summary text or to make it the first child of the details section as the Azure docs do.

[wbamberg]

This is now done!
-> #313 supported JS sidebar in content-side
-> mdn/yari#370 supported rendering it