Clicking on a package in API Reference ToC collapses the Side Nav

[mehzer]

Which is irritating. Suggest that API Reference is a separate Side Nav. Click behavior from regular Docs is to shift to that Nav and maintain current position in the menu expand/collapse.

[joeduffy]

I noticed this too; this is due to the way our TOC code -- which is a rat's nest of Jekyll madness -- does matching of paths to highlight left hand navs (https://github.com/pulumi/docs/blob/master/_includes/toc.html). It doesn't work well for anything beyond the top level topics.

@lukehoban had argued against a separate API side nav, by the way, so you guys should hash this out.

Regardless of where you land on that decision, the nav logic will need to be fixed (I believe it would even be a problem with a distinct API docs reference section).

[mehzer]

I'd argue, but I'm tired from the cramp of having to keep expanding and scrolling to click. :)

…

On Wed, Jan 30, 2019 at 10:14 AM Joe Duffy ***@***.***> wrote: I noticed this too; this is due to the way our TOC code -- which is a rat's nest of Jekyll madness -- does matching of paths to highlight left hand navs (https://github.com/pulumi/docs/blob/master/_includes/toc.html). It doesn't work well for anything beyond the top level topics. @lukehoban <https://github.com/lukehoban> had argued against a separate API side nav, by the way, so you guys should hash this out. Regardless of where you land on that decision, the nav logic will need to be fixed (I believe it would even be a problem with a distinct API docs reference section). — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#814 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABgGxt09qltlAAX661xzDiJb5lCtmQeNks5vIeEIgaJpZM4aaxHk> .

[lukehoban]

I think we need to decide whether to have a unified TOC or not. If we do, it has to have great ergonomics for expanding/collapsing sections, as it will in general be big and multi-layered.

Right now, we have a very confusing mix- where we have three top level tabs - "Getting Started", "Documentation" and "APIs" - and the latter two share a TOC, but the former is its entirely own TOC.

I have argued in the past that a single overall TOC helps all content be discoverable, and puts less pressure on finding a "perfect" information architecture, because it's easy to explore the content. The lack of the "Getting Started" pages in our current "Documentation" TOC for example makes it very hard to find answers things like "How do I configure Pulumi for Azure?". That content happens to be under "Getting Started", but it not available in the "Documentation" TOC.

[justinvp]

I would like to see a unified TOC. In the meantime, I've addressed this specific issue with #829

[joeduffy]

I'm curious if you have example docs websites that use unified, "big and multi-layered" TOCs like this that you recommend we draw inspiration from.

None of my favorites do this, so it's hard for me to envision what it would be like. For example

• Heroku: most similar to ours today
• Serverless: starts with one TOC, but specializes as you drill down into cloud-specific "user guides"
• Terraform: multiple top level sections

Part of the problem here, I would assert, is that our tutorials are still poor (they should be much more like Heroku's and/or what our Tour used to be like), and we've mixed things in there, like Installation and Provider Configuration, that should not be underneath a tutorials section (this would still be a giant discovery problem even with a unified TOC IMHO -- I'm not sure having it there and letting people click around randomly in unintuitive places truly solves the problem...)

[justinvp]

Fixed by #829 (and in the process of being deployed to production). Opened #831 to track considering a unified TOC.

[justinvp]

Sigh, #829 only fixed the issue for top-level packages, but drilling down into modules still has the issue. Opened #832.