Anki Manual Improvement

Anki Help
1

I try to be brief, but it is not an easy topic.

I don’t aim to criticise anything, I am thankful for anki, it is a really valuable contribution to making the world better. I really appreciate it. And I personally start to like it.

My point is the manual. I Have difficulties with it, and want to suggest a kind of endeavour to improve it.

But I don’t know if this is appreciated at all.

I tried to start something on the anki reddit, but I just can’t post over there.

In my opinion the anki manual needs more care.
I experienced it being difficult to start with anki, it has a steep learning curve (imho).
Wouldn’t it help to make Anki more popular, by improving it’s documentation ?
I give examples.

Example 1)
Under “key concepts” you find “Types of Cards” and then later “Card Types” - both refering to completely different concepts. I think, for the former, “Card Status” might be more adequate.

Example 2)
I understand the buttons “Again”, “Hard”, “Good”, “Easy”. I also understand the numbers above: It is the consequence of pressing that button to the time when the card will be shown again, in accordance to the concept of spaced repetition, and it’s optimisation(s).
However, it is difficult to relate this to the deck-options.
For example, the explaination on “Learning steps” says "…The first delay will be used if you press the “Again” button, … The "Good " button will advance to the next step.
With “Step” is it meant “Advance to the next DELAY” ?
And, what if THEN, after advancement, “Again” is pressed ? Will it go back to the previous delay ?
and so son.
Sugestion: Wouldn’t it be useful to have a kind of flowchart to explain these mechanics ?

Example 3)
The structure of the manual is
(1) Quickstart -->going to “Getting Started”
installing
videos
key concepts
(2) getting help
(3) translations

I think it should be more something like this:

  1. Introduction
    Here, briefly mention the key concepts and what is anki all about.

  2. Using Anki
    Learning
    Here, explain how anki is used, with the buttons, what the mean, how the behave mechanically,
    how the time values are related to it,

    explain the options more tidy, more convenient, in short, clear sentences.

    Managing Learning Decks
    Creating / Editing Cards
    Card Types
    Creating / Editting Decks

  3. Installation

  4. Online resources
    Getting Help
    Videos

** Example 4 **
In the categories if the Anki Forum, there is no place for “Documentation”,
and the existing categories “enforce” to relate questions or topics to a specific platform version, which is not adequate for general questions in the anki software itself.
So, I can’t even post this in the right place. I posted it to “anki desktop” in lack of a more suitable place.

I am willing to help making the manual better, if this is needed and wanted, but I need some
correspondance to work on anything.

2

As for no.2: There is a example in the manual that describes clearly how learning steps work: Deck Options - Anki Manual. If someone can’t understand the shorter explanation in the help box in anki there is a link to the manual there.

As for no.3: The key concepts behind anki are explained in the first chapter of the manual: Background - Anki Manual. An overview of anki concepts is presented in the Quick Start chapter with more detailed explanation following, for example: how the time values are related to buttons is explained in the chapter after that, Studying.

As for no.4: There is a Suggestions category that imo this post would fall under.

I myself find the anki manual to be very clear and helpful but i do agree that we could do something to make it more accessible/prominent, so new users know where to go first when they encounter any questions and how to navigate it.

2 Likes
3

Thanks a lot for caring to read it all.
And also thanks for the suggestions - that truely helps.

I agree, the manual is apparently very good.

Maybe, me as a newbie, perceive it differently than someone who is already familiar with it, thus my struggles.

Obviously, the manual is rather elaborate, because anki has so many features.

Anyway, what would be an approach to improve the manual ?
For example, I might intend to create a flow chart for the card meachanics (the V3 scheduler, as I now understand).
Is it right to just checkout the git repo, edit the manual, and send a pull request,
so some insider can review that, and then integrate the change into the manual ?
If so, where is the manual in the git repo ?
Or is it a better way to discuss this first with someone who is responsible for the manual ?
And, ist is OK to use mermaid for that ? Or better plantuml ? Or graphviz ? No kidding, I worked with all of those. What would the anki creators prefer, if that would be needed at all ?

I start to get a vision, having a big map of a flow chart explaining all the nitty gritty details of anki.
This is what I sometimes do as a software engineer as part of my usual work.

4

In my opinion a flow chart for card mechanics would not have to be more complicated than what can be found on wikipedia under spaced repetition: File:Leitner system alternative.svg - Wikimedia Commons.

I would avoid any UML charts - while they could be very useful in understanding how the anki works on the back-end (it took me some time to notice how different parts of code interlink with each other in anki source code) - someone who is not experienced in reading those would have hard time understanding anything, so they wouldn’t help a majority of new users.

I do think a simple diagram describing how the front and back of a card template, card types, note types, notes and decks interact with each other (one note can have multiple card templates, those have a back side and front side, etc.) would help a lot, I encounter a lot of people who have a hard time understanding those relations.

1 Like
5

Maybe this can be helpful to clarify some key concepts:

I agree, some areas of the manual can be improved, you can help directly here, I suggest starting with small PR:

1 Like
6

Agreed - previous flowcharts I’ve seen people create of deck options/study screens don’t seem to make things any clearer IMHO. They’re also harder to maintain than simple text-based descriptions. But note/cards/templates are a common source of confusion, and some graphical representation of them could well help with that.

7

What about adding FSRS into this page?

https://faqs.ankiweb.net/what-spaced-repetition-algorithm.html

FSRS has become the most popular algorithm add-on.

image
image1156×429 54.3 KB

image
image770×469 35.4 KB

2 Likes
8

I’ve added mention of it on that page.

1 Like
9

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.