Tabs for documentation!
nathan-contino opened this issue · comments
It would be nice to have the syntactic sugar of tabs in our documentation. Tabs represent 'parallel steps' in a guide: essentially, anywhere in a guide where you do A OR B OR C. Consider the following section flow in a guide:
- download foo
- install foo via CLI
- install foo via GUI
- run foo
Without tabs, this looks like you perform steps 1 -> 2 -> 3 -> 4. In reality, you perform 1 -> 2 OR 3 -> 4.
With tabs, you can model this as:
- download foo
- install foo (contains tabs CLI and GUI)
- run foo
This more accurately conveys that users should choose CLI OR GUI.
For example:
- https://www.mongodb.com/docs/atlas/device-sdks/sdk/java/quick-starts/quick-start-local/ (kotlin and java tabs -- note that the tabs apply to an entire section, not just a single code snippet -- some of the java tabs contain more than 1 code snippet whereas the equivalent kotlin tab contains only 1)
- https://www.mongodb.com/docs/atlas/app-services/sync/error-handling/client-resets/#enable-or-disable-recovery-mode (GUI vs CLI -- extremely relevant to our docs, which frequently explain how to do something on the Raspberry Pi Desktop, then on the CLI)
Example use cases:
There are many! Just linking a couple:
- https://www.raspberrypi.com/documentation/computers/configuration.html#audio-configuration ("Desktop volume control" or "Using raspi-config", mutually exclusive parallel steps)
- https://www.raspberrypi.com/documentation/computers/configuration.html#change-a-users-password doesn't use sections, but "raspi-config" and "passwd" are mutually exclusive parallel steps)
- https://www.raspberrypi.com/documentation/computers/configuration.html#configure-screen-blanking excellent example of potentially nested tabs, and an especially confusing current flow: "Desktop" vs. "Console" are two mutually exclusive parallel steps. "Raspberry Pi Configuration" and "CLI" are two mutually exclusive parallel steps within the higher-level Desktop step! For clarity, this example should be converted to two tabsets with the following structure:
- Desktop
- Raspberry Pi Configuration
- CLI
- Console
Known issues/gotchas to look out for:
- The order of tabs and default displayed tab should always be consistent for a given tabset. For instance, for the tabset CLI OR GUI, we should always default to a specific option (in this case, probably GUI). The default option should probably appear first (leftmost) in the list of tabs.
- When multiple sets of tabs exist on the same page that contain the exact same collection of tab options, choosing a tab in a single tabset should switch ALL of the tabsets. For instance, if a guide page contains a CLI OR GUI tabset in the "install" section towards the top, and a CLI OR GUI tabset in the "register" section towards the bottom, choosing the CLI option in the "install" section at the top should also change the tabset in the "register" section at the bottom. This means users don't have to repeatedly choose the same tab if multiple tabsets occur on the same page!
- Whenever a user changes tabs, the page should not scroll. The top of their visible page should stay in the same position. If the page sometimes bounces around when the user changes tabs, they'll quickly learn to be afraid of changing tabs since it means losing their place in the guide!
I think that might make things much easier in code sections, different languages, different Pis etc. Not sure how it would work with Asciidoc source though.
@JamesH65 I've got a rough plan for how to handle this in the asciidoc / converted HTML, but the more specific use cases & examples y'all can provide, the better (so I can take into account all the possible variables...).
I'll email you off GitHub since this repo is public.