Too many demos (aka: documentation overhaul)

I think most of the current demos can be helpful to the students to get to know some tricks of Pelita and the demos being self-contained files that can be run on the command line makes it much easier to experiment with.

However, this format also turned out to be a problem for students who are more used to reading documentation than reading code. Less because of the code but because there are just too many files to look at, which for many students isn’t a thing in their usual workflow. So what happened was that students would read the first few demos and when they came to the first one that was half-useful (basic attacker or basic defender), they’d work on that file but only rarely do a switch to any other file in the demos, especially not the later ones.

(Aside: Maybe we should also have a bit of a talk during the school on how to set up and use a good visual editor that can read a project and give contextual auto completion. It is a bad sign when you as a tutor go to a student who asks for help with their code, you tell them that they should look in demo xy for a solution or a helpful comment and they close their current file or even their text editor before they open the other file.)

It can be hard to change people’s preferred workflow in one week but a mitigation would be to integrate all demos in a sphinx/mkdocs website with some introductory text explaining what it does and the full source code.

tl;dr: Students are bad at reading two Python files at the same time but don’t mind having 10s of tabs open in their browser.

ASPP / pelita_template

Too many demos (aka: documentation overhaul) #40