I think stripping things back and aiming for simplicity,
less code, more info about how to create cards,
and aiming at beginners to intermediates.[^1]
Issues should be handled better, keeping them simple enough to not scare beginners off (think kids) and ones that are "for my eyes only" kept hidden somehow. Try to encourage some kind of interaction for those who use the tool regularly.
Simplify initial README so it's easier to digest. Show it, don't say it! Remember some of the books you've read that are too fussy worded and academic. Reduce!
Add some gifs and videos. User pain points. Easy install. Ditch the professional docs.
[ ] Make sure you've got a demo of the best feature in the documentation!
110 (for intermediate users 🧑🎓)
[ ] Potentially (but no guarantees) make some "reveals" more standout (subtly)
125 (at the very least, blur the "question" (code block) and highlight the "answer" (code block)
129
In general cards should created in a simple way that makes the answer obvious (isn't always easy)
[x] Remove solved issues
Add a note in the documentation where appropriate
118
132 Add a very specific note about selecting text right to the end of the line in docs.
81 Run through these quickly and do the easy stuff where necessary.
89 Salvage any useful thoughts from here (such as bold don't {{cloze::...}})
12 Add a "note to self" for using fonts in the future. Especially variable fonts.
[x] Remove advanced documentation — if they really need it, it isn't so hard to figure out. We can leave that there for posterity in a previous commit.
Keep things simple wherever possible
Have a simple section on compiling the data files with Pandoc
Keep the CSS styling section simple too, they can use one of the other Skylighting themes if they prefer.
Make sure they know they'll have to create their own config file for css if they want to keep any changes for future updates.
[x] Data folder (compiled files)
Currently shows Pandoc's default css, not our custom css
I'm thinking to take the hit on nicely formatted "preview" data files and just stick with the *-stripped.html output files for speed of adding cards.
98
Remove the data-Anki classes
[x] Converting "data" from Markdown to HTML (with Pandoc) comes with some problems
You have to make sure you don't copy/paste the surrounding tags[^2]
I don't see anyway around this and you'll just have to use common sense (and a little prompting) to copy/paste the data
[x] Anki Child Theme seems defunct
I'm reasonably confident the majority of people using this are "rip and run" types.
I'm hazarding a guest
[x] Simplify the code colours
Start with one of the defaults, for instance — and they're really quite basic — and look at some simple examples of dark and light themes with other code highlighters, compare and contrast. It doesn't have to be Solarized or Monokai — but get it right!! Simplify!
134 (just do your best)
Apart from --color-code-light-background all the css variables underneath #2 can go.
Explore the possibility to use pygmentize with Pandoc. It might be slighly better colour tokens.
[x] #79 Give night mode a quick try (wait until other CSS changes are done)
It's best I think this out a bit first, the colour palette needs some consideration.
[^1]: The problem with using Anki for advanced stuff is that there's a whole lot more code involved. It's still possible to use it, but you have to be quite careful with your card creation. It needs to be to-the-point, only hold the specific problem, with specific code, that can be viewed in 30 seconds or less. When you get to that point, sometimes a file with comments is better.
[^2]: For instance, with missing-stripped.md, the ★ Title mentions in the comments auto wrapped in a h1 tag, meaning **only the code inside the h1 tag is needed to copy/paste.
badlydrawnrob
commented
2 weeks ago
Issues should be handled better, keeping them simple enough to not scare beginners off (think kids) and ones that are "for my eyes only" kept hidden somehow. Try to encourage some kind of interaction for those who use the tool regularly.
Simplify initial README so it's easier to digest. Show it, don't say it! Remember some of the books you've read that are too fussy worded and academic. Reduce!
Add some gifs and videos. User pain points. Easy install. Ditch the professional docs.
110 (for intermediate users 🧑🎓)
125 (at the very least, blur the "question" (code block) and highlight the "answer" (code block)
129
118
132 Add a very specific note about selecting text right to the end of the line in docs.
81 Run through these quickly and do the easy stuff where necessary.
89 Salvage any useful thoughts from here (such as bold don't
{{cloze::...}})12 Add a "note to self" for using fonts in the future. Especially variable fonts.
*-stripped.htmloutput files are useful, but when rendered in the browser they won't render properutf-8characters.*-stripped.htmloutput files for speed of adding cards.98
data-Ankiclasses134 (just do your best)
--color-code-light-backgroundall the css variables underneath#2can go.pygmentizewith Pandoc. It might be slighly better colour tokens.[^1]: The problem with using Anki for advanced stuff is that there's a whole lot more code involved. It's still possible to use it, but you have to be quite careful with your card creation. It needs to be to-the-point, only hold the specific problem, with specific code, that can be viewed in 30 seconds or less. When you get to that point, sometimes a file with comments is better.
[^2]: For instance, with
missing-stripped.md, the★ Titlementions in the comments auto wrapped in ah1tag, meaning **only the code inside theh1tag is needed to copy/paste.