Modern Python Projects Transcripts
Lecture: How to write good documentation?
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.