HackMD
Documentation lesson plan
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
