---
# System prepended metadata

title: Documentation lesson plan
tags: [lesson materials]

---

# 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
