Docs: Article TOC improvements

[svick]

Currently, article TOC shows only H2 headings. I think it should also show lower level headings. This is especially useful on articles like Documenting your code, which have only few H2s, but lots of H3s.

Also, it would be useful if the article TOC stayed on screen when scrolling down in the article. This makes navigating inside the article easier, because it means you don't have to keep scrolling to the start of the article to get to another section. (But if doing that, also make sure articles where the TOC is higher than the screen size work well and that the whole TOC is accessible.)

[cartermp]

Agreed, especially this:

Also, it would be useful if the article TOC stayed on screen when scrolling down in the article.

Particularly when reading a long article, this is difficult to deal with.

[mairaw]

/cc @DuncanmaMSFT

I believe we have a feature request to have the TOC always visible. Duncan, can you confirm?

I think having H3s visible could be something configurable. Like I really wanted the project.json article to show the whole tree, but always showing H3s might get too cluttered. We'd have to test.

[BillWagner]

I like the idea of showing all the headings on the right hand side.

I'll propose that any topic that has so many headings that the right hand side requires scrolling has too many headings, or is long enough that it should be broken up.

[stevehoag]

This sounds like something that could benefit from some A/B testing to see what our customers prefer.

[DuncanmaMSFT]

FYI, one part of this "Also, it would be useful if the article TOC stayed on screen when scrolling down in the article." is already live on that page ( https://docs.microsoft.com/en-us/dotnet/articles/csharp/codedoc ). As to the second, that's an interesting feature request... @mairaw if you want to file a feature request into the VSO site

https://mseng.visualstudio.com/VSChina/_workitems?witd=Feature&id=1&_a=new

Area is VSChinaDocs Site and Services
Iteration is VSChinaBacklog

Assign to me, and I’ll distribute accordingly

[mairaw]

Nice that we got that in this week @DuncanmaMSFT. I'll file a feature request for the other then. I'll go though msdnhelp and assign the values after the request is created since they told me never to file them directly. :smile:

[mairaw]

@BillWagner how would you do that for project.json reference for example? it would require scrolling if we add H2s and H3s and I don't think it should be broken up.

Also, how do you guys feel about the TOC on the left-hand side? On MSDN, only the article scrolls and both the main TOC and the article TOC are always visible. We now have the article TOC visible, but if I link you to here from another topic, you have no clue where you are unless you scroll.

In addition to that, I've noticed that the breadcrumb is not showing the path where you are for the conceptual docs. Not sure if it's just a configuration issue.

[BillWagner]

@mairaw Good point.

This could be quite a bit of CSS and JS code, but consider:

. The Left side TOC should be scrollable, and should scroll such that the current page is in view on page load.
. The right side TOC should also scroll, and the current anchor should be in view whenever the current line changes.

[mairaw]

/cc @EisenbergEffect

[EisenbergEffect]

The sticky ToC and scrolling has been implemented and released. We are already tracking a feature request for H3 to be added to the "In This Article" UI. It's a bit lower priority right now due to the importance of other ship-blocking features that the engineering team is working on. It also received heavy push-back from the design team. I think it's something that should be considered again though, since we've got multiple customers (internal and external) that are now asking for it. Additionally, I know that for some articles the "In This Article" UI is virtually useless without it showing H3s.

[mairaw]

Closing this one since this is not related to our content but to the site experience and they closed this one as won't fix:
https://github.com/MicrosoftDocs/feedback/issues/278