Background
I’m planning to open a few PRs in the future to reduce the perceived cognitive load (make the manual easier to understand) and got a few questions.
Q1 – Should I prefer smaller sections or longer sections?
When I say section then I mean the page you get when you click on a menu item in the sidebar, e.g. Styling & HTML - Anki Manual.
Pros: Making them as small and atomic as possible is good because it feels less overwhelming for most people.
Cons: I personally dislike having to click on a billion links just to see the next bit of information – I don’t really mind having a longer site like the link I provided above, if the site is well structured and readable.
Q2 – Should subsections generally be avoided?
With subsections I mean the things like 7.1, 7.2, ect. as shown in this picture:
I don’t really think they should be avoided per-se but just double checking for the standard here. This question also somewhat depends on Q1.
Q3 – How do I handle changing headings?
Some headings are links, e.g. this one: Styling & HTML - Anki Manual.
If I wanted to remove a heading or rename it, how would I handle it correctly? I think if I remove or rename it, then it might break links that are already used in the forum and on other places. Should I:
- Avoid changing them at all costs?
- Just change them and do nothing more?
- Change them if I see fit, but make sure to include some hrefs (I think I read that that’s a way to link old links to the new headers)?
Q4 – How to handle the table of contents?
David pointed out to me that having a table of content with half the page or longer (on mobile) could be an issue for users.
How should I handle that? Should I hide them by default using something like this?
<details>
<summary>Table of Contents</summary>
<!-- toc -->
</details>
(see Update background.md to reduce cognitive load by GithubAnon0000 · Pull Request #344 · ankitects/anki-manual · GitHub for pictures)
Or prefer subsections instead? Or something else maybe?