[Documentation] How to deal with sections, subsections and links?

Anki Development
1

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:

anki
anki434×227 12.6 KB

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:

  1. Avoid changing them at all costs?
  2. Just change them and do nothing more?
  3. 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?

2

May I ask for your guidance and opinion on this one @dae?

3

Dae seems to be quite busy and seems to have a big backlog (or missed this mention).

@Danika_Dakika and @sorata: you two are quite involved in documentation as well. Do you maybe know an answer to a few of my questions?

Would be nice if it had an official doc or if it where part of the style guide.

4

I’ll just quickly respond to one query.

Normally, we’ve been adding a <div> so that the old links work. Mdbook also allows you to have a header id that gets used in a link, while the header is named something completely else. Refer to the mdbook docs for details of this.

About sections, where do we need completely new sections? I’m a bit uneasy about taking existing content and putting it on a new page. That’ll mean the old links wouldn’t work at all.

1 Like
5

For every heading? Or is there any distinction made?

6

I mean, there haven’t been many changes in heading titles.