Modern Python Projects Transcripts
Chapter: Documentation
Lecture: How to write good documentation?
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
Now, how do we actually write a good documentation? Do we dump everything on one page, or do we split it into separate pages?
0:09
If, yes, then how do we split it? If you don't know how to structure your documentation, you can use the following documentation system.
0:17
It splits documentation into four categories. First, we have tutorials. Their purpose is to. Teach new user how to use your project.
0:26
A good example is the quick start guide that explains how to install all the dependencies
0:32
of your project and how to get your application up and running on someone's computer.
0:38
In our case, a tutorial could explain how to install this calculator module with pip and how to start using it in a Python terminal.
0:46
Next, we have how to guides they are goal oriented, and they explain how to do a specific task with your project.
0:53
With our calculator, we could write a how to guide on how to other bunch of numbers together. It's not very useful how to guide,
1:01
but I hope you get the point. Third category is explanations. They explain how your project works behind the scenes and how
1:08
different parts interact with each other. we could explain how the calculator plus works.
1:13
For example, we can explain that we can change command calls because we return the calculator Instance. Finally, we have reference category, reference
1:22
Guides are like a Wikipedia page for your project. They should describe every part of your application, all the classes, all the functions,
1:31
all the methods, what parameters they take what they return. So all the API documentation falls into this category.
1:39
In our case, we could take the API documentation from the doc strings and turn it into a reference guide. I didn't come up with this classification.
1:48
I got it from Daniele Procida. Excellent talk on how to write documentation, of course If you like to write your documentation in a different way,
1:55
that's great. There is no one perfect way to document every project. But if you don't know how to start,this system is pretty good.