 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. 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 Piperland Meetup. And over to you, Anastasia. Very great to have you here. Hello, everyone. Thank you for inviting. I hope the sound sounds great, right? All good? Yes, it's all good. If anything happens with the slides, I just don't see this screen. I have all the presentation all over the screen, so just interrupt me. It's all fine. OK. So hello, everyone. My name is Anastasia, and a few words about myself. I'm joining from Berlin. I'm working as a lead developer at Scout B. I play a lot of different roles at the same time. Sometimes I'm writing the code, sometimes documentation, sometimes just writing some papers at work. At my free time, I'm a Piperland 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, 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 today is not about me. It's about you. It's about documentation and your code. If that would be a live event, I would ask you to raise a hand if you document 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 that time, when I wrote my first program, just step by step by the book, it looked so perfect, 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 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. 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 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 said little code, which was a bit lost in its lifetime. No one wanted to play with the set 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 experienced in retrospective. So the set code had so many questions about its lifetime and there were no answers. And there was just a set cat sitting next to him, such a sad story, right? So the set 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. 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 end point is weird. We don't really know what is actually happening in there. 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 end point? That's why the code was sad because no one wanted to play with it. 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 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. 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. This approach includes writing how to use, 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 read me file 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. And then after adding a read me 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 understood that there is a friend? There was a notification. Boom, there is one star appeared, one new friend. 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. 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. 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 Sphinx documentation for this code specifically. So after adding the read me, the set code decided, well, this the first advice followed along quite nicely and then let's try the second one. And you got another friend. Fantastic, another star appeared. Okay, great, let's take the third advice. The third advice showed the set code 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. 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 a non-series. So after this advice, 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 and that's a fun part because the references can include the code reference, for example, and this could be auto-generated for a Python code. So in our case, we can use the code reference while using Autodoc from Sphinx and even host it on with the docs. We will see that in the demo further alone. 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. 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 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. 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. So what is it? Did you guess already? Because 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're right. And these four pieces of advice were all about 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. And I have a question for you. Would you recommend 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. So if this example did not convince you enough to start working on the documentation, I have a few more points of advice for you from my experience. Documentation is important. Yes, but why? Because people forget things because whenever people leave the code alone 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 afloat your head from all of this burden and just enjoy your life. 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 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. 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 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. 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. 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 can be found in the documentation divya.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. 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 Sphinx, well, some people I heard are afraid to use it 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 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, 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. 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. 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 api doc to go over your code to generate 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. 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 strings you have in your files. There is 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? 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%. That means that not every function and not every file has to be annotated with the doc strings. The doc strings would look like, if you are not familiar, this is a simple application which has a hello world. It's not that said anymore. This is the doc screen for the function, for the endpoint, and this is the doc screen 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 with interrogate on the CI. And then maybe you would see all the fancy stuff. Let's see, that's not the one. I have a few failed, no. 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. So the documentation itself, if you use the simple setup of read the docs, this is a standard one, which I just took from read the docs, 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 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. 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, but you can add many more. So this is pretty much it with the demo. Just as a reference, you remember our set code. So it can make us happier if we add the code reference, 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 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, 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, 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 the stock. I would really love to hear back from you and enjoy the documentation, enjoy the GitHub setup in here. Please let me know if you want to get any more advices. You can find me in Twitter or in the next Fibrillini tab and we can go to questions. If there are any. All right. Hi, Anasa. Hi, Anastasia. Sorry, I keep getting names wrong. We do have some questions and first off, thanks for that amazing talk. So I'm going to display these questions down below and I'm going to also read them out so we can answer them. So do you have any thoughts on documentation as a hard requirement for defining done when it comes to new features, general development? Well, we are 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 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 guides. So it depends what kind of feature is it. If it's a feature which would, I don't know, 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 and then try to focus on this. Oh, you're muted. Sorry, online conferences. Yeah. So in your experience, did you find interrogate potentially counterproductive by forcing desk 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. At the beginning, it could be simple, but then you never know if it's simple in a year. It's just, 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. It's so great because obviously we are experienced developers. Well, not in Python, but it's 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? 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 at the beginning, but then as long as this is a culture in the team, 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? Let me turn off the ticker. Yeah. Yeah. Oh, okay. I guess it's just... Yeah, yeah, no worries. Input and return should be, yes. It should be a part of doc streams. The input parameters return and also the doc screen explaining what this function does. I didn't have this in the example because, well, this is Hello World. It doesn't have any input parameters. It doesn't pretty much return anything except Hello World. But yes, it should be in there. 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 joined the talk and see you hopefully in the offline conference or next steps.