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