Continuous Documentation: basics and advanced techniques

Documentation is an important part of each project, but it does not mean that it’s always up-to-date. Updating documentation continuously is quite a lot of work and not every project has a capacity to invest so much time into it, especially when a project is on a tight release schedule.
This talk will show you the basics of a good documentation and you will learn about different types of documentation, how to use and when to write them.
Anastasiia will also share her experience on how to introduce documentation as a part of your team’s daily routine and update it continuously.

From this talk you will learn:

how to start with documentation for your code,
how to make your documentation to update continuously,
running Python code inside of your documentation with PyScript,
documentation best practices.
After this talk you will be able to check out my repo with a few samples of different types of documentation as a part of continuous documentation for a dummy piece of code.

Transcript

1. anastasiatymo Continuous Documentation: basics and advanced techniques by Anastasiia Tymoshchuk anastasiatymo
2. anastasiatymo Engineering Mamanager at Strava in Berlin PyBerlin organiser 
 https://www.meetup.com/PyBerlin/ 11 years in software development 7 years in Python Happy Pythonista 🐍 😊 Few words about myself
3. anastasiatymo Photo by Wesley Tingey on Unsplash Do you document your code?
4. anastasiatymo Me 10 years ago..
5. anastasiatymo • people forget things • people leave the code alone • new people come to contribute
6. anastasiatymo How to start?
7. anastasiatymo • choose main source/tool for documentation
8. anastasiatymo • make sure that it's up-to-date • build a team culture around documentation
9. anastasiatymo Let's start with basics
10. anastasiatymo Do you document your code?
11. anastasiatymo Do you document your code?
12. anastasiatymo Do you document your code?
13. anastasiatymo How to add documentation to this code?
14. anastasiatymo Goal-oriented approach - How-To Guides Source: https://diataxis.fr/how-to-guides/ "How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented. How-to guides can be thought of as recipes, directions that guide the reader through the steps to achieve a speci fi c end."
15. anastasiatymo
16. anastasiatymo Learning-oriented approach - Tutorials Source: https://diataxis.fr/tutorials/ "Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind."
17. anastasiatymo
18. anastasiatymo Understanding- oriented approach - Explanation Source: https://documentation.divio.com/ "Explanation, or discussions, clarify and illuminate a particular topic. ... Explanation clari fi es, deepens and broadens the reader’s understanding of a subject."
19. anastasiatymo
20. anastasiatymo Information-oriented approach - Reference Source: https://diataxis.fr/reference/ "Reference guides are technical descriptions of the machinery and how to operate it"
21. anastasiatymo
22. anastasiatymo "In other words, what we call documentation is fundamentally not one thing, but four. Understanding the implications of this, and how those four di ff erent things work, can help improve most documentation." Source: https://diataxis.fr/
23. anastasiatymo
24. anastasiatymo Looks better now?
25. anastasiatymo Photo by Beatriz Pérez Moya on Unsplash How to actually start? • start as simple as possible • go to version controlled docs
26. anastasiatymo Photo by Beatriz Pérez Moya on Unsplash • add docstrings to your code • use Sphinx, MkDocs to prepare documentation • try Read The Docs, GitHub Pages • add more documentation
27. anastasiatymo Demo?👩💻 https://github.com/atymoshchuk/simple_docs_setup
28. anastasiatymo
29. anastasiatymo
30. anastasiatymo Sphinx & PyScript
31. anastasiatymo https://github.com/Je ff ersGlass/ using-pyscript-in- documentation
32. anastasiatymo Sphinx & Jupiter Notebook
33. anastasiatymo https://nbsphinx.readthedocs.io/en/ 0.2.15/index.html
34. anastasiatymo You can not force people to read documentation
35. anastasiatymo Photo by Wesley Tingey on Unsplash https://www.meetup.com/PyBerlin/ Thank you! https://github.com/atymoshchuk/simple_docs_setup