Continuous Documentation for your code
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 115 | |
| Author | ||
| Contributors | ||
| License | CC Attribution - NonCommercial - ShareAlike 4.0 International: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/58743 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
00:00
Execution unitCodeCASE <Informatik>Disk read-and-write headComputer-assisted translationBitDifferent (Kate Ryan album)Right angleProjective planeLine (geometry)Arithmetic meanPoint (geometry)Set (mathematics)Video gameReading (process)Software developerForcing (mathematics)CodeComputer fileoutputTouchscreenFunctional (mathematics)Electronic program guideConfidence intervalData conversion1 (number)Parameter (computer programming)Module (mathematics)Computer configurationService (economics)Formal languageMereologyStreaming mediaCoefficient of determinationComputer programmingEvent horizonCartesian coordinate systemBranch (computer science)Library (computing)Multiplication signRevision controlProcess (computing)Configuration spaceElectric generatorWeb-DesignerSoftware repositoryLink (knot theory)Fiber (mathematics)Open sourceSelf-organizationPresentation of a groupWordSlide ruleHypermediaDemo (music)Basis <Mathematik>Computer architectureMoment (mathematics)Type theorySemiconductor memorySoftwareLatent heatSeries (mathematics)InformationBoom (sailing)CollaborationismShared memoryOrder (biology)Ocean currentStrategy gameSoftware testingWritingMessage passingVariable (mathematics)Mobile appINTEGRALTrailGoodness of fitMeeting/Interview
01:02
Gamma functionSoftwareSoftware developerWeb-DesignerDifferent (Kate Ryan album)Freeware
01:50
CodeGoodness of fitMultiplication signOnline chatComputer animation
03:03
CodeMessage passingWordDigital photographyPermianMessage passingParameter (computer programming)CodeComputer-assisted translationBitComputer programmingConfidence intervalComputer animation
05:39
Normed vector spaceDirection (geometry)Open sourceCodeElectronic program guideAnalytic continuationComputer animation
06:16
CodeCodeDemo (music)Software developerSet (mathematics)CollaborationismComputer fileComputer animation
07:05
CodeLatent heatElectronic program guideOrder (biology)Computer animation
07:48
CodeSet (mathematics)CodeLatent heatComputer animation
08:18
CodeNormed vector spaceDigital photographyCodeCASE <Informatik>Series (mathematics)Right angleSoftware repositoryComputer animation
09:12
CodeAttribute grammarDigital photographyOpen sourceInformationElectronic program guideGoogolSoftwareSoftware developerBlogCodeMereologyDemo (music)Software developerProjective planeSoftware repositoryOpen sourceElectronic program guideTrailBitRevision controlComputer fileArithmetic meanVideo gameMultiplication signType theoryDisk read-and-write headMoment (mathematics)Semiconductor memoryComputer animation
16:22
WebsiteInternet service providerGame theoryFunction (mathematics)Directory serviceComputer configurationInternet forumVirtual realityComputer-generated imageryBuildingOpen sourceCodeAverageGroup actionLine (geometry)Text editorError messageInstallation artEmailPrisoner's dilemmaCodeStreaming mediaComputer fileFunctional (mathematics)TouchscreenCartesian coordinate systemSoftware repositoryComputer fontElectronic program guideDemo (music)Configuration spaceProcess (computing)MultiplicationProjective planeLink (knot theory)Computer animationSource codeXML
19:29
CodeModal logicWebsitePrice indexTable (information)Function (mathematics)Musical ensembleRevision controlOpen sourcePhysical systemCodeDemo (music)Computer fileModule (mathematics)Computer configurationComputer animation
21:15
CodeForm (programming)Digital photographyBitCodeComputer-assisted translationComputer animation
21:50
Digital photographyPoint (geometry)Forcing (mathematics)Line (geometry)CodeMereologyReading (process)Computer animation
22:58
Vector potentialCodeSoftware developerFunctional (mathematics)INTEGRALParameter (computer programming)outputWritingData conversionStrategy gameSoftware testingStreaming mediaMereologyVariable (mathematics)Service (economics)Meeting/Interview
Transcript: English(auto-generated)
00:06
So now we have Anastasia with us. She's going to talk about continuous documentation for your code. She has worked in development for more than 10 years, including experience in e-commerce, as well as game development.
00:20
She also deals with a lot of challenging questions about architecture and deployments on a daily basis. And she's currently working as a tech lead, helping to build an engineering culture in her team and serve her team's needs as a leader. She's also an organizer of PyBerlinMeter. And over to you, Anastasia. Very great to have you here.
00:41
Hello, everyone. Thank you for inviting. I hope this sounds great, right? All good? Yes, this is all good. If anything happens with the slides, I just don't see the screen. I have all the presentation all over the screen. So just interrupt me, it's all fine. Okay. So hello, everyone. My name is Anastasia.
01:00
And a few words about myself. I'm joining from Berlin. I'm working as a lead developer at ScoutB. I play a lot of different roles at the same time. Sometimes I'm writing the code, sometimes the documentation, sometimes just writing some papers at work.
01:20
At my free time, I'm a PyBerlin organizer, and you're all invited. I have a very different experience in software development from game development to business development. And that helped me to learn a lot, actually. And the last seven years, I stayed in Python,
01:40
so it's my preferred language, and I'm still happy just because of the community. The community is great and fantastic, and I'm really happy to share my experience today with you. But you know, today is not about me, it's about you. It's about documentation and your code. If there would be a live event, I would ask you to raise a hand if you document
02:01
your code, so if you want to participate in that, please write something in the chat. So around 10 years ago, I remember myself at the time when I wrote my first program, just step by step, by the book, it looked so perfect,
02:21
or I thought that it was perfect. But it didn't feel right, and it didn't feel quite finished. At that point, I didn't know what to actually check in my code and how to know when it's good enough, or when it needs more work to be ready to go into code review even. And after I passed the code review and merged it
02:42
to the main branch, I was not still sure if it would be good in, let's say, five or six years, or maybe even one year. Obviously, I was not thinking about documentation, and I didn't know that it's needed. Well, maybe I did know, but it's not quite in the books.
03:05
And just 10 years later, I realized that the confidence comes with experience, with failures and successes, with learning from others, and trying different approaches. But what if you could possibly travel to the future
03:20
and ask your future self how to make this code better? In this talk, we will be able to experience some magic and travel to the future. So let the future begin now. Let's start with some interesting story about a sad little code, which was a bit lost in its lifetime.
03:41
No one wanted to play with the sad code, and it was wondering if there is a possibility to find out how to deal with the new code and new services, how to talk to others, how to get new friends, and how to look at all the issues it was experiencing in retrospective. So the sad code had so many questions about its lifetime,
04:02
and there were no answers. And there was just a sad cat sitting next to him. Such a sad story, right? So the sad code was wondering what is wrong with it and how to change to get new friends. Let's take a closer look into this code.
04:21
Why is it so sad? First function, as you can see, this is a Fast API example, simple hello world. It does return a message, hello world. Pretty simple, pretty clear, pretty nice. The second endpoint is weird. We don't really know what is actually happening in there.
04:41
There is even a weird message. So there is a message return. There is a parameter one, and then some other optional parameters, and there is no explanation what does the parameter mean, and why do we need to use this endpoint? That's why the code was sad because no one wanted to play with it.
05:02
So do you remember the story I started at the beginning? There was a very, very sad code, and the cat, obviously. The code went to sleep and something magical happened. It met someone. It met its future self. The future self said, I will give you four pieces of advice
05:21
which will improve your communication, and at the end, you will have to solve the riddle. Follow my advice to reclaim the ancient knowledge and gain the programming superpower. You will shine for many, many years.
05:41
So listen carefully. And the set code said, yes, please continue. The first piece of advice showed the set code how to use problem-oriented approach to show the world how to solve the problem if there are any in the future.
06:00
This approach includes writing how-to guides. Those guides are like a recipe when you go step by step and then you achieve something in the end. For example, if you want to set up a simple documentation for your code, you can add a simple readme file
06:22
to guide the developer through the installation steps, maybe collaboration steps. That would be a good start. No worries. This example is quite small, but we will see that later on in the demo. So the first advice was applied by the set code.
06:41
And then after adding a readme file, something magical happened. The set code noticed that it got a friend. Can you imagine? A new friend, how about that? But how does the set code understand that there is a friend? There was a notification. Boom, there is one star appeared, one new friend.
07:03
Fantastic. Okay, let's follow along. So the second advice showed the set code how to use learning-oriented approach to show the world what the code is actually doing. These are the instructions with the clear steps, what is needed to be done in order to build something to achieve some goal.
07:22
Don't confuse yourself with the previous one, the how-to guides. Tutorials are quite different. Tutorials teach you not to cook a specific recipe, but to just cook in general. Like you don't know how to work with this specific piece of code.
07:41
Then you can follow along maybe a few times, repeat it a few times, maybe gain more learning, more knowledge from that. So let's see. In our case, that could be a tutorial how to set up basic things and documentation for this code specifically. So after adding the readme,
08:01
the set code decided, well, this is the first advice, followed along quite nicely, and then let's try the second one. And he got another friend. Fantastic, another star appeared. Okay, great, let's take the third advice. The third advice showed the set code
08:21
how to use understanding-oriented approach to explain the world more about its personality and about how the code feels about other services, packages, or maybe even integrating with others. In our case of the set code, we can even explain something like the motivation,
08:40
why do we need documentation, why all of this is useful. So anything that could clear up things, explain something extra, accept the how-to guides and follow along series. So after this advice,
09:01
obviously we got even more friends That's great, fantastic. Everyone is actually keen on checking the repo right now, I'm sure, and giving more stars to it. So then the last but not least advice showed the set code how to use information-oriented approach. That's actually about references,
09:20
and that's a fun part because the references can include the code reference, for example, and this could be auto-generated for Python code. So in our case, we can use the code reference while using AutoDoc from Sphinx and even host it on readtodocs.
09:41
We will see that in the demo further along. So after this four wonderful advices from the future, something truly magical happened. The code woke up, and then it was not just set anymore. It felt comfortable to go to the party, to meet others, to start talking to developers who even started the code.
10:03
So then in a few years, the code finally met its creator, the developer. The developer, there was a sparkle between them, and it means that they understood each other, and then after even a few years, they were deeply connected,
10:20
and they could talk to each other. So something truly magical happened. At that moment, the code had a flashback in the memory to the moment when the future self asked to solve a riddle. And here it is. I'm someone who can teach you a lesson, but not a teacher.
10:42
I'm someone who can guide you to a goal, but not a tour guide. I'm someone who can tell you everything about technical specs of your functions, but not an encyclopedia. And I'm someone who can explain you a particular topic to help to understand, but not Google.
11:01
So what is it? Did you guess already? The code started thinking and finally realized something. So wait, you are my future self, and all the hints were about you, right? The future self answered, yes, you are right, and these four pieces of advice were all about me,
11:20
tutorials, how-to guides, explanation, and the reference guides. So are you a documentation? Yes, said the future self, I am, and you are right. The secret is that it needs four types of documentation to make a great software, not just one.
11:46
And I have a question for you. Would you document your code knowing its future, knowing that documentation can make your code shine for many years, would you do that? Okay, you can write the answers later on.
12:03
So if this example did not convince you enough to start working on the documentation, I have a few more bites of advice for you from my experience. Documentation is important, yes, but why? Because people forget things. Because whenever people leave the code alone,
12:23
and they're not touching it, then they can forget things. We're just all humans, that's quite normal thing. And no matter how you try remember things, you don't have to, you can offload your head from all of this burden and just enjoy your life.
12:41
And also new people come to contribute. It doesn't mean that people leave the companies or projects or teams, but people also move through different projects over time. Because I don't know, there are reasons. Maybe business reasons, maybe some person got bored
13:00
and wanted to start contributing to something new. Or maybe this project is open source, and then somebody new to open source just came there and wanted to contribute. But how to do that? If you cannot read documentation, you cannot really know what to do and how it looks.
13:22
So I would really suggest you to focus on this. And you know, this is so true. Documentation cannot be out of date if you don't write any documentation. But if you actually decided to add some documentation to your code or write a new code
13:42
with documentation already, I have a few checks for you to make sure that you're on the right track. So the first one would be to choose the main source tool for documentation. You just need to decide what kind of tool would you like to use. For Python, for me, that was super simple.
14:02
I just used the same approach that I tried before. It worked, but it could be anything else. We will go to that in the demo. Then make sure that your documentation is up to date. That's really important if you write it.
14:20
So how to actually start? I would suggest you to start as simple as possible, and then maybe you can try something interesting. Go to version control documentation. I suggest you first to read a few articles so the entire inspiration and the types of documentation
14:41
can be found in the documentation.devio.com. And there are also good examples how to write documentation. You can get more inspiration. You can also read another articles which would motivate even more why should you write the documentation.
15:01
I will stop for a second so you can maybe take a screenshot. And if you use Python, I have a few tools for you. So what I used in my previous and the current projects that's Sphinx. Well, some people I heard are afraid to use it
15:23
because it's not so easy to set up, but I have a repo for you with the simple setup. So you can just copy paste it and then just start with it. And you can try read the docs. Actually, this provides you possibility not to save all the HTML generated files
15:42
from the Sphinx documentation. They will host it, they will run it for you and then they will keep all the versions for you. There are a few versions of read the docs. One is the business one. So if you have closed repo, for example, and you don't want anyone to see your documentation only inside of the company,
16:01
you can pay a bit of money for that. And then you can have full support from readthedocs.com. There is another version which is readthedocs.org which is open source and fully free. So you see there is already a benefit of using this tool.
16:25
So what I would like to do right now is to go to some simple demo of the documentation. You can see here the repo which you can check out later. I will post the links somewhere. I did some job this night actually to add more documentation for you to see.
16:44
To start, you can actually go to docs and then check the setup in here. The main setup is done in the configuration file. This is a Sphinx configuration. And there is a function which runs the appy-doc
17:01
to go over your code to generate a code reference. Then if you're still not sure how much documentation do you want, how much do you need, I suggest you just to run it and then see how it looks. As you can see, there is a README file.
17:20
I did add some stuff, how to run Docker. So this is how-to guide. After that, there is a simple setup for the CI. You would say that CI is not related to any documentation, but it is. There is a way to check how many doc streams you have in your files.
17:42
There is a documentation coverage tool which is called Interrogate, this one. You can also have a specific setup for your project. What exactly would you like to check? Would you like to annotate init files, for example, or not?
18:02
Which folders would you like to check? For example, if you have maybe just a library, not a service, then you would have multiple folders in here. And then you can also put the coverage of the documentation. For example, you want the coverage to be not 100%, but 80%.
18:21
That means that not every function and not every file has to be annotated with the doc streams. The doc streams would look like, if you're not familiar, this is a simple application which has a hello world. It's not that sad anymore. This is the doc screen for the function for the endpoint.
18:44
And this is the doc stream just for this package, the file. Because if you don't put this one, the top one, it would be 50% of the coverage for this specific file. And you can also go verbose when checking the documentation setup
19:03
with Interrogate on the CI. And then maybe you would see all the fancy stuff. Let's see. That's not the one.
19:22
I have a few failed fonts. No. Okay.
19:46
Okay, that would be a long story. If you wanna check how the CI works and you wanna go verbose and then see file by file how Interrogate goes through the files, you can add an option and then it will have the entire summary of it.
20:03
So the documentation itself, if you use the simple setup of Readtadocs, this is a standard one which I just took from Readtadocs. You can use exactly the same one. You can also use a custom theme for Sphinx documentation. You can put it here as a folder
20:22
with all the custom themes. And well, can you give me a charger please? And actually this is the simple setup of the Sphinx. This is how it looks. And then it has the intro that we checked.
20:43
It has all the documentation. Why do we need documentation? And also the code reference. It doesn't have so much because basically the modules are empty
21:00
but you can add many more. So this is pretty much it with the demo. Just as a reference, and you remember our set code. So it can make us happier if we add the code reference,
21:23
if we add simple setup of the how-to guides, then we add a bit of tutorials and then we get more explanation to the users. So then this code, even the most set code ever can be super happy and the cat can be happy
21:40
and it can get so many friends as possible, maybe even more than 51 in this case, and our future self would be extremely happy. And as a last point for today, that's something that I recently realized. You can force people to write documentation because you can add interrogate, for example,
22:02
to interrogate your code on how many lines you have of documentation, but you cannot force people to read documentation. That's not possible. People will not ever read documentation if it's not a part of the culture. So if this is not a part of the culture in your team,
22:20
for example, you have to start small. You have to start bringing this as a culture. And that was great. You were a great audience. I hope you really liked this talk. I would really love to hear back from you and enjoy the documentation, enjoy the GitHub setup in here.
22:41
Please let me know if you want to get any more advices. You can find me in Twitter or in the next PyBrillini tab. And we can go to questions, if there are any. All right, hi Anastasia.
23:02
Sorry, I keep getting names wrong. We do have some questions and first off, thanks for that amazing talk. So I'm gonna display these questions down below and I'm gonna also read them out so you can answer them. So do you have any thoughts on documentation
23:20
as a hard requirement for defining done when it comes to new features, general development? Well, we're starting with not so easy questions. I do have some thoughts. You have to first document requirements for the feature because then you will forget it
23:41
in a few weeks or maybe a month and then you will not even know the motivation why this feature was implemented and how. And just general advice just to add doc streams which is easy and fast and maybe some how to guide. So it depends what kind of feature is it. If it's a feature which would, I don't know,
24:02
allow to collaborate with other services so that integration is important. If it's a feature for users, then it would be important for developers to know maybe a testing strategy or something that could be used in a year. So just think what could be useful in a year for a person who never worked with this one
24:22
and then try to focus on this. Oh, you're muted. Sorry, online conferences.
24:41
Yeah. So in your experience, did you find Interrogate potentially counterproductive by forcing devs to write documentation for things that need none? Perhaps because the code is so simple, it is self-explanatory. Well, at the beginning it could be simple. So that's a tricky question.
25:01
At the beginning it could be simple but then you never know if it's simple in a year. If it's simple in half a year and then you will not even remember anything. People tend to forget. I remember when we started developing the code with a team, we didn't know any Python. We just learned and we saw that this code is just perfect.
25:22
It's so great because obviously we are experienced developers. Well, not in Python but still fine, right? We didn't write any documentation and after a year I was checking the code and I was wondering who wrote this stupid code and why is it so unclear how to even use it.
25:40
And yeah, that was me obviously. We had to rewrite a lot of things because it was not so clear how to use it, how to test it and we were not also good with variables which was not readable. So it could be annoying in the beginning but then as long as this is a culture in the team,
26:01
it would get better I would say, yeah. I promise it will get better. Just keep up with the documentation. So the next question is slightly linked to the previous one as well. And the question is, do you think code details like input and returns should be in the documentation?
26:24
Let me turn off the ticker. Yeah. Yeah. Okay. I guess. Yeah, yeah, no worries. Input and return should be, yes. It should be a part of docstrings.
26:41
The input parameters return and also the docstring explaining what this function does. I didn't have this in example because well, this is hello world, doesn't have any input parameters. It doesn't pretty much return anything except hello world but yes, it should be in there.
27:00
All right, thank you. Those are all the questions that we have right now and you can further take on this conversation within the Optiva breakout room. Okay, cool. Thank you so much. You are a great audience. I hope you really enjoyed the talk and see you hopefully in the offline conference
27:20
or next steps.