search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
18.05k stars 1.63k forks source link

"Toggle table of contents" icon is hard to recognizable #1296

Open RalfJung opened 4 years ago

RalfJung commented 4 years ago

It just took me around half a minute to find a way to hide the table of contents in an mdbook. The problem is that the icon to do so is the "hamburger icon" which is usually used to indicate "click this to open a drop-down menu that shows more options". I don#t think it is a good idea to use the same visual language to say something totally different.

The icon I would have expected is something like an arrow to the left to hide the ToC, and an arrow to the right to show it again. This is e.g. what GitLab does for controlling the menu on the side.

Confusingly, sometimes there is a huge arrow to the left (like here), but that dos not hide the menu, it goes to the previous chapter.

ehuss commented 4 years ago

I wouldn't say it is "something totally different". The hamburger icon is commonly used to show contents or sidebar navigation. For example:

It is commonly taught to use a hamburger to show/hide navigation sidebars.

Of course, not always. There are some other options. Examples of non-hamburgers:

I would say the hamburger is by far the most common visual language for this on the web and mobile UIs.

It's hard to put myself in the shoes of someone who has never seen an mdbook site, so it's hard to say how discoverable it is. There are tooltips that tell you what it is. And as mentioned, there is already arrows used for page navigation, so I think using a left/right arrow could be more confusing. I'm not sure how it could be made more discoverable.

I have occasionally thought about some kind of "how to read the documentation" helper. Maybe a question mark could open an overlay that explains the different UI elements and keyboard shortcuts?

RalfJung commented 4 years ago

It is commonly taught to use a hamburger to show/hide navigation sidebars.

Interesting, I have not encountered this a single time. I have seen hamburger menus mainly in local applications -- Firefox, Thunderbird, many Gnome applications. Every single one of them uses it as an abbreviation for "here comes the application menu".

On mobile, it's similar -- hamburger opens the application menu, e.g. in OsmAnd. Maybe you consider "main application menu" and "navigation sidebar" to be the same thing? They feel very different for me -- but maybe that's because I feel like desktop does (and should) use a pretty different visual language from mobile? Note that they also work very differently -- these main application menus (on desktop an mobile) appear on top of the main page/app content. They are ephemeral; you open them, click something, and then they disappear again. That's very different from an mdbook table of contents (which is shown by default, its persistent and sticks around after you click an item within it) in terms of how the interaction works, hence I would never expect them to use similar icons.

Here's how it looks for GitLab: https://gitlab.mpi-sws.org/iris/iris. I am pretty sure I have seen similar things elsewhere, but I cannot think of an example off the top of my head.

gitbook: https://docs.gitbook.com/

There is an icon for "contents" there on the right but it's not the usual 3-line hamburger. It's a bunch of horizontal lines (more than 3!) on different indentation levels to indicate how a TOC looks. This icon makes sense to me, but it's very different visually from what mdbook uses.

docusaurus: https://docusaurus.io/docs/en/installation

I cannot see a men/hamburger icon here.

bookdown: https://bookdown.org/yihui/bookdown/ docsify: https://docsify.js.org/#/

Agreed, this is the same as mdbook.

vuepress: https://vuepress.vuejs.org/guide/

I cannot see a hamburger on that page?

nuxtjs: https://nuxtjs.org/guides/get-started/installation

No hamburger/menu icon that I can find.

ehuss commented 4 years ago

On several of these sites, the hamburger only shows if the window is too small.

image image

etc.

mdbook behaves similarly, where if the window is too small the sidebar is automatically hidden.

RalfJung commented 4 years ago

Oh I see, interesting. But then when the page is small, it behaves exactly like the hamburger menu in Firefox! The menu is not shown by default, clicking the hamburger shows the menu, clicking an item in the menu hides the menu again. That is the interaction I expect from a hamburger menu.

It is not the interaction of the hamburger icon in mdbook. Clicking it does not open an "overlay menu" that disappears again after choosing an item in the menu. So I maintain that the icon makes sense for how those websites use it, but does not make sense for how mdbook uses it.