Simplify things for end-users

[badlydrawnrob]

Aimed predominantly at beginners and intermediates.
Professional build is being removed, but link back to previous versions.
Install. Update. Pandoc builds. Issues.

The ___ ways to learn

I feel some of the best learning is applied learning ...
This is where key learning points meet unfamiliar territory.
You can also lock-in this learning with flashcards.

A learning path is a difficult one to pin down, but a key ingredient is "don't hide behind research!" — meaning, if you want muscle-memory with coding, do it often (even if a little a day) and just start building! You can be learning and building in parallel, learning "just enough" to get by. Books are a great resource, but they're often hand-holding. The real test of knowledge is in its application (not simply knowledge in and of itself). As always, mentorship and feedback helps.¹

1. Baby steps (every single step is hand-held, even mistakes)
2. Scaffolded courses (each chapter builds on preceding one)
   • ALWAYS be consistent between chapters here (continuation errors)
3. Fix it! (existing code with a learning point to fix)
4. Finger exercises (HTDP mini "exams": DIY) - These are unfamiliar domains with familiar syntax
   • However, each question is very concrete with little creativity
5. Mini-briefs
   • These are lead by the tutor, given within a learning framework ...
   • It's a bit like finger exercises but more creative!
   • It means each student's results are varied (can be hard to manage)
6. A pet project (a real life app or example) - Here we shape concrete proposals
   • These proposals require distinct learning criteria ...
   • Which is often in unfamiliar territory and requires domain knowledge ...
   • But has meaning to the student, in their own words (great way to learn)
7. A job. Not all of us want to take this route ...
   • But real-world learning happens "on the job"
8. Teach it to a child
   • Part of the Feyneman technique: how well do you understand it?

Write up some simple examples

Nice example overviews: Elixir, intro to elm
No academic or overly complicated language

• Good and bad card examples for [type of card]
  • Good (and bad) examples of cards #114
  • Prioritise beginners, ease-of-use, and advice on card creation #150
• Simplify initial README so it's easier to digest
  • How to use Anki and creating cards #123 (condense and simplify)
  • Show it, don't say it. Gifs and videos.
  • A simple PDF for instructions?²
• Compiler stuff is hidden until required (intermediate)
  • This takes considerable amount of teaching
• Common pain points handled with a FAQ etc
  - See Discourse new user tips and tricks for good example

Other things

• Aim to keep issues simple
  • Personal issues should remain personal (e.g. Auto update package.json? #102)
  • Perhaps a tags are enough: "don't worry about this!", "for beginners only", etc
• Updating Anki deck #42 updates should be inviting and simple.
  • The briefest of notes on this in the README and the UPDATE
• A very brief word on security
  • Getting syntax highlighting to work #25
  • Keep the Pandoc commands obvious, because the documentation is far from obvious
  • Use npm, but a couple of notes on how to use Pandoc.³
• Badges and questions
  • I've barely had any questions or user-led issues, so no need for templates yet
  • Perhaps a simple sentence/section like this forum
  • Simple instructions for "Learn", "Show and Tell", etc, if they want.⁴
• Regularly check links are working
  • From time to time, easiest way for internal links is to hover over link in Visual Studio Code⁵
  • This can also be done with the Marked App (external links at least) Preview -> Validate External Links
• Semantic Versioning is a useful reminder
  • Make json easier #44
• Simplify and gut some features #135
  • Make sure the data files work smoothly with Pandoc
  • I feel the stripped versions are quicker to use.

Footnotes

1. The amount of learning can become overwhelming with programming, and knowledge is easily forgotten without practice (or familiarity) so concrete projects are some ways to ease the burden. ↩

2. If I can't easily do this for both Github and Marked with the same markdown code, I'm not wasting my time. Eventually it might be nice to have a small indy site for this. ↩

3. We're not using templates or anything like that, but it's helpful to note you can change the theme easily if you want to, either by editing the --css-variables or --highlight-style and manually editing the css. I don't think I'll include all the themes by default as some of them are a bit rubbish. ↩

4. So far the way I've approached this has been unsuccessful. I don't really know how often people are using this tool, or how long it serves them. At least one person has a very old version, and another only needed it for a very short spell. ↩

5. Using a link check tool online is another option, but it display all Github's links too. ↩