Reorder episodes to adhere to general aim #321
Description
Thinking a bit more about #317, but in concrete.
Since we really want to stress sphinx/github pages, and that is the cool stuff, we might change the structure of the lesson so that it matches this aim.
We do not need to talk about motivations or show a taxonomy of tools before we start talking about in-code documentation, READMEs and sphinx. These topics are a little abstract and are, actually, implicitly based on what existing tools can do.
I think it makes sense to have a crescendo, like this:
- It makes sense to talk about in-code documentation at the beginning because code comments are something that everybody writes.
- It makes sense to talk about READMEs because it's an introduction to Markdown. There are some cool features in plain READMEs too. And that's also a clear "upgrade path" from no README at all.
- showing Sphinx after READMEs really sound like an upgrade.
- deploying Sphinx docs to GitHub pages is the climax.
After that, we can put things into context with a talky part where people can chill/fall asleep/get going with practice
- Why we don't like wikis instead? Why we like to have documentation version controlled in the same repo as the code (apart from the publishing mechanism of ghpages)? -> Motivations and wishlist
- What if I don't like sphinx? Can I use something else? What about tool X? What am I missing with sphinx? -> Popular tools and solutions