Documentation lesson plan

# Documentation lesson plan :::danger Radovan to screenshare and type (if that is ok, Samantha does not have time to fix her current issues with setup :( ) ::: **09:00 - 09:10** Motivation and tools create a wishlist in collaborative notes Lead: Samantha 10min * 2 exercises in 20min and roughly one hour after the break one break at 11.00 EEST * programming language independent * README * documentation generator * publishing docs on github pages Tell: * Starts with naming things. * Part of code, evolve with code * human and machine readable (notes as example) Motivation-1 and Motivation-2 in notes Finding time is hard, why bother? What to focus on? Collecting tips * Is project documentation important? Why? * How would you describe a useful documentation? * How can you motivate your colleagues to contribute to the documentation? Think about projects you found, what did you like? * Let us create a wishlist for how we would like documentation to be. **09:10 - 09:20** In-code documentation, Writing good README files brief discussion Lead: Radovan \+ intro to exercise + brief wrapup after 20 min **09:20 - 09:40** Exercises: README-1, README-2, README-3 (choose one or multiple) 9:40 check notes, radovan starts **09:40 - 10:00** Sphinx and Markdown: Sphinx-1 as type along Lead: Samantha \+ intro to exercise Lesson material written in Sphinx -> great way of presenting clean documentation; many styl9ing possibilities (annotation, highlight, code boxes, ...) while still human readable Show lesson page and source With sphinx, we can build html page locally and later publish it on website Software verification -> Radovan to type Sphinx-1 as type along -> Radovan to type 20min * Understand how static site generators build websites out of plain text files. * Create example Sphinx documentation and learn some Markdown along the way. **10:00 - 10:10 Break** **10:10 - 10:40** Exercises, Sphinx-2, Sphinx-3, GH-Pages-1 * Why does it suddenly look different? * How does it actually work? * Jupyter **10:40 - 11:00** Discussion, GH Pages, Summary Lead: Radovan 20min