[00:00.000 --> 00:11.920]  So, hello everyone. My name is Anastasia and I can say a few words about myself before
[00:11.920 --> 00:18.400]  we start today's talk. I came here from Berlin. I live in Germany, Berlin, for already seven
[00:18.400 --> 00:24.880]  years but I'm from Ukraine originally and I play a role as an associate director of
[00:24.880 --> 00:32.800]  engineering at SoundWide in Berlin. Also, I'm one of the organizers of PyBerlin Meetup and I have
[00:32.800 --> 00:38.880]  11 years of experience in software development and seven of them in Python. You can see how happy
[00:38.880 --> 00:48.400]  I am with Python and I can share and I will share my long road to programming actually with
[00:48.400 --> 00:55.280]  documentation and you will learn from me what I learned through all the years of software
[00:55.280 --> 01:04.320]  development. And let's start today's talk with a question. Do you document your code? So,
[01:04.320 --> 01:15.040]  rise a hand if you do, write documentation. Wow, a lot. Nice. Okay. That's very nice. So,
[01:18.560 --> 01:24.640]  some years ago, around 10 years ago, when I just started, I remember myself, I started
[01:24.640 --> 01:31.360]  programming language. I took a programming book, then I just went by the book. I wrote a
[01:31.360 --> 01:38.960]  Hello World program. It was very nice. It looked so perfect. I did the first pull request into
[01:38.960 --> 01:46.960]  our code and I thought it was very perfect. It looked so great. It was approved but it didn't
[01:46.960 --> 01:52.640]  feel right. I didn't even know what to check but I just didn't feel right and I was not sure
[01:52.640 --> 02:01.280]  would this code still be live or there in some years or maybe in six months or somebody will
[02:01.280 --> 02:08.880]  just change the code and then it would be not good anymore. And when I even passed the code
[02:08.880 --> 02:14.400]  review, I merged the code. I was still not sure what to check in the code and when to consider
[02:14.400 --> 02:21.840]  that the code is good enough. And of course, I didn't know about documentation. I was not told
[02:21.840 --> 02:32.240]  that I should write documentation in my code. And today, we're going to look into the 10 years
[02:32.240 --> 02:41.680]  after I started. So, after all of this time, I realized that experience comes together with
[02:41.680 --> 02:47.200]  the confidence of you more. You are more confident in the code that you're writing because you're
[02:47.200 --> 02:53.600]  writing a lot and then you learn from other people. You go to the conferences. You listen
[02:53.600 --> 03:00.320]  to all the talks, all the experiences. You talk to other developers in the community. If you're
[03:00.320 --> 03:11.280]  open source developer and there is no documentation, it's a bit tricky. So, what if me 10 years ago
[03:11.280 --> 03:17.440]  could possibly travel into the future and listen to this talk and know what to do from the very
[03:17.440 --> 03:24.480]  start? I would be maybe happier in my life. I would not do so many mistakes as I did through
[03:24.480 --> 03:30.800]  all the years. And that's why we're here. I'm going to show you things that I learned over the years
[03:30.800 --> 03:38.080]  and we are going to have a bit of a magic today happening following the 10 years into the future.
[03:38.080 --> 03:48.080]  So, let the future begin now. Let's start with the story of one little set code
[03:48.800 --> 03:55.280]  which was lost in its lifetime and no one wanted to play with this code. This is the code that I'm
[03:55.280 --> 04:07.120]  talking about. And the code was just sitting there very sad, very little, wondering why am I so sad,
[04:07.120 --> 04:15.360]  why no one is talking to me. And had no clue how to deal with other services or other developers
[04:15.360 --> 04:22.560]  and had so many questions in its lifetime. And the only sad cat was sitting and supporting that
[04:22.560 --> 04:31.680]  set code. So, the set code was actually wondering what is wrong with it and how to change to find
[04:31.680 --> 04:38.800]  new friends. Let's take a look into the code. So, the first function, it's pretty clear. It's just
[04:38.800 --> 04:45.680]  the hello world, the basic stuff. But if you look to the second one, this is the sad part.
[04:47.440 --> 04:54.160]  So, there is a function with some of the arguments and some of the results returning something but
[04:54.160 --> 05:01.680]  not very clear, not very clear the outcome of the function, what does it do, what is the purpose,
[05:02.240 --> 05:09.600]  also names of the parameters where they lost at some point. So, you remember the story,
[05:09.600 --> 05:17.120]  there was a sad code, very sad code, and just the cat sitting next to the sad code. And the code
[05:17.120 --> 05:25.440]  went to sleep. And something truly magical happened. It met someone. It met its future self,
[05:25.440 --> 05:32.080]  just right 10 years after. And the future self said, I will give you four pieces of advice
[05:32.080 --> 05:38.640]  which will help you to improve your communication skills. And in the end,
[05:38.640 --> 05:45.280]  I will give you a riddle to solve. So, follow my advice to reclaim the ancient knowledge
[05:45.280 --> 05:49.600]  of programming superpowers and you will shine for many, many years.
[05:52.720 --> 06:00.400]  So, let's start. Then listen carefully. Yes, the sad code said, please continue. So,
[06:00.400 --> 06:07.120]  here is my first advice to you. This is the way how to use the goal oriented approach
[06:07.120 --> 06:15.360]  to show the world how to solve a problem if there are any in the future. This approach is about
[06:15.360 --> 06:20.880]  writing how-to guides. So, those are basically the directions to the reader and you can read
[06:20.880 --> 06:30.240]  a bit more in the links which I listed over there. This is the most used guide, the most searched
[06:30.240 --> 06:38.720]  and the most read and basically everything written about the code. It includes like a recipe
[06:39.440 --> 06:46.560]  or the direction for solving a very specific problem. So, if you are trying to create something
[06:46.560 --> 06:54.160]  of the how-to guide about something very specific, not very about everything like how to create a
[06:54.160 --> 07:00.000]  web server, something that would not be a how-to guide, but something how-to create for a very
[07:00.000 --> 07:06.080]  specific reason. That would be a how-to guide and those are actually very specific guidelines
[07:06.080 --> 07:12.000]  that we are usually looking for because we have all of the specific issues and then we are searching
[07:12.000 --> 07:16.480]  for a specific piece of information for a specific problem as a solution.
[07:16.480 --> 07:26.640]  So, with the first piece of advice, the set code was thinking, okay, I can improve by just writing
[07:26.640 --> 07:33.200]  a simple set up, how to set up myself to be open for others. So, that's a very specific
[07:33.200 --> 07:40.560]  what to install, where to install and added some read me file to the guideline of the code.
[07:40.560 --> 07:49.360]  And then, after following that advice, the set code noticed that they got a friend. Can you
[07:49.360 --> 07:56.720]  imagine? A friend, a real friend. How do I know that? Well, just look at that. There is a star
[07:56.720 --> 08:04.640]  shining. Well, that was just the start, the first one. So, the second advice show the set code how
[08:04.640 --> 08:11.680]  to use learning oriented approach to show the world what actually is done by this code. So,
[08:11.680 --> 08:18.960]  those are the tutorials. Those are a bit different from the how-to guides in the way that this is
[08:18.960 --> 08:24.240]  more like learning by doing. So, you are not reading all the documentation. You are just
[08:24.240 --> 08:30.960]  doing an exercise like a teacher showing in the school what to do to learn a specific subject.
[08:30.960 --> 08:38.400]  So, if we are talking about the code, then just follow the advices also would be learning by
[08:38.400 --> 08:48.080]  doing, writing some specific tutorials would be to achieve some goal, but it doesn't have to be a
[08:48.080 --> 08:56.720]  very specific problem to be solved. So, if we are following the advice, the set code was thinking,
[08:56.720 --> 09:03.600]  okay, maybe I can add a bit more. Let me write some tutorial about basic things set up, how to
[09:03.600 --> 09:11.840]  write it, how to build it, and then something happened again. There was another friend. Look
[09:11.840 --> 09:18.960]  at that. The second star is shining. Already good. Good path. The third advice showed the set code
[09:18.960 --> 09:25.840]  how to use understanding oriented approach to explain more what the code is doing. So,
[09:25.840 --> 09:30.320]  those are the explanations, different discussions on very specific topics which are
[09:30.880 --> 09:37.360]  broadening the main subject. So, if we already have the basic documentation, we have the how-to
[09:37.360 --> 09:47.040]  guides, we have different learning by doing exercises. Those are explanations are very,
[09:47.040 --> 09:55.120]  very specific. So, if you compare to a recipe book, this is not a recipe book. This is more of a
[09:55.120 --> 10:02.720]  reference of the different ingredients, how to get the ingredient, for example, or which
[10:02.720 --> 10:11.760]  ingredients are particular for a very specific dish. This is everything that could tell the
[10:11.760 --> 10:17.120]  said little code how to do with different packages or different services, how to integrate with
[10:17.120 --> 10:24.240]  others. And, of course, the set code did implement something like this. So, they wrote a bit of
[10:24.240 --> 10:32.400]  more explanation on why do we need documentation in general. And, again, it was very helpful,
[10:32.400 --> 10:37.440]  very happy. So, the set code was thinking, okay, and more friends are coming. That's great.
[10:38.320 --> 10:45.440]  Let's go to the last advice. So, the last but not least piece of advice was about information
[10:45.440 --> 10:53.680]  oriented approach, about references. In software development, reference guides are usually describing
[10:53.680 --> 11:00.080]  the functions, the input, output, arguments, the results of the functions, key classes,
[11:00.080 --> 11:06.720]  different API. So, everything that is about the code, about different attributes, it doesn't
[11:06.720 --> 11:12.800]  have to be every single function, but it should be all of the main key classes, key functions that
[11:12.800 --> 11:19.680]  are used. So, then, afterwards, you can recap and then look just the 10 years after you can look
[11:19.680 --> 11:30.720]  at what was done before. And, just like that, the set code followed the fourth piece of advice
[11:31.440 --> 11:41.200]  and decided to write a code reference, added that, and also applaud that to somewhere for others to
[11:41.200 --> 11:50.480]  see. And, after those four wonderful advices from the future self, something really magic happened.
[11:50.480 --> 11:56.720]  The code woke up, not very sad anymore, not mad, and it felt very comfortable to go out and then
[11:56.720 --> 12:04.640]  talk to others, connect to other developers. And, then, after some time, the set code remembered
[12:04.640 --> 12:12.560]  that there was a riddle, the future self said there would be a riddle, and then you will
[12:12.560 --> 12:19.600]  gain the superpowers, right, where is the riddle. So, here it is. I'm someone who can teach you
[12:19.600 --> 12:26.240]  a lesson, but not a teacher. I'm someone who can guide you to a goal, but not a tour guide.
[12:27.920 --> 12:33.120]  I'm someone who can tell you everything about technical aspects of your functions,
[12:33.120 --> 12:39.760]  but not an encyclopedia. I'm someone who can explain you a particular topic to help you to
[12:39.760 --> 12:55.120]  understand, but not Google. Can you guess what that is? Okay. So, the code was very happy because
[12:55.120 --> 13:03.760]  they knew the answer already and asked the future self, so, well, look, was it all about you? All
[13:03.760 --> 13:10.080]  about you, my future. So, you are documentation. So, you are really my future. And, the future
[13:10.080 --> 13:16.160]  self said, yes, those four advices were all about me. I'm your future. I'm your future. Fantastic
[13:16.160 --> 13:21.040]  documentation with the tutorials, how to guides, explanation, and the references.
[13:21.040 --> 13:29.520]  And, in other words, we all need to understand that documentation is not a single piece.
[13:29.520 --> 13:37.040]  It's more than that. It consists of four different types of documentation, and it's very important
[13:37.040 --> 13:46.000]  that we add all of them, and we at least have some sections of those to focus for our future
[13:46.000 --> 13:58.480]  selves, not to be in trouble. So, just to recap the future of that little code is now, it's about
[13:58.480 --> 14:08.480]  code references, tutorials, explanations, how to guides, and that would make your code happy,
[14:08.480 --> 14:14.480]  and the cat, of course. And, it would get many friends, especially in open source, it's very
[14:14.480 --> 14:20.240]  important to add documentation and to explain what is code actually doing and all the functions.
[14:21.200 --> 14:28.960]  And, that would be a really bright future. So, I have another question for all of you. Would
[14:28.960 --> 14:42.320]  you document your code after all of you heard in the future? So, if this example didn't convince
[14:42.320 --> 14:49.040]  you, I have a few more pieces of advice from myself, from my own experience, why do we need
[14:49.040 --> 14:57.680]  to document code? Because people forget things. Even if you wrote the code, you will forget about
[14:57.680 --> 15:04.000]  it in a week, in a month, in a day, or maybe something happens, and then, well, you return
[15:04.000 --> 15:09.520]  back to the code and then you don't remember why it was it. People leave the code alone,
[15:09.520 --> 15:17.200]  and this is also important. If you are working for open source, you can give it to somebody else,
[15:17.760 --> 15:21.200]  you leave it alone, then you come back, you need to review, and then, oh my God, I didn't
[15:21.200 --> 15:27.440]  remember that function. Then, new people come to contribute. This is also very important. They
[15:27.440 --> 15:35.520]  need to know how to contribute, what to contribute, what is important for this. So, how to start?
[15:35.520 --> 15:44.720]  First, you need to choose, you need to choose main source tool for documentation,
[15:45.600 --> 15:50.640]  and then, of course, you need to make sure that it's up to date. So, the continuous documentation,
[15:50.640 --> 15:57.360]  it's a culture. It's not the thing that you can force people into. You need to make it as a culture
[15:57.360 --> 16:03.280]  for yourself and also for other people. So, I would recommend you to read a few things.
[16:03.280 --> 16:10.880]  This was the original document where it's actually written about those four pieces of
[16:10.880 --> 16:16.320]  documentation. I recommend you to go through it, read more about different types of documentation,
[16:17.120 --> 16:22.880]  then also what are the documentation about the legacy code, and the real Python has a very
[16:22.880 --> 16:31.520]  nice tutorial about documentation with MK docs and also GitHub pages. So, how to start? You need
[16:31.520 --> 16:36.880]  to start as simple as possible. This is the best solution. Just start some basics. Then, you can
[16:36.880 --> 16:44.640]  go to version control documentation, and that will be like a next level. So, you have Python code,
[16:44.640 --> 16:51.920]  you need to document something. First, what do you do? I would say you start documenting. So,
[16:51.920 --> 16:56.320]  for that, you need to add some doc strings to your code, then you will take them and then make a
[16:56.320 --> 17:01.840]  reference guide, which is already nice to have. It's out of the box. It can be auto-generated if
[17:01.840 --> 17:09.360]  you host it somewhere so beautiful and easy. And for that, you can use Sphinx MK docs to prepare
[17:09.360 --> 17:15.440]  the documentation, also put some files. And, of course, you can try to host it somewhere
[17:15.440 --> 17:22.000]  like read the docs, which is free for open source projects or GitHub pages. Well, there are other
[17:22.000 --> 17:28.480]  tools, but those are the ones I used. And, of course, add more documentation. So, if you want to see
[17:29.120 --> 17:38.400]  those pieces of documentation that I showed, here is the link where they are. And also, you can
[17:40.480 --> 17:46.000]  see in here, so this is how the read the docs would look if you would use it for a simple project.
[17:46.000 --> 17:53.120]  And this is how the Sphinx documentation that I showed you with the set code would look like.
[17:55.280 --> 18:02.880]  And to then just to remind you that you cannot force people to read documentation. You can force
[18:02.880 --> 18:08.720]  them only to write documentation. So, if you want to make sure that your documentation is up to date,
[18:08.720 --> 18:15.200]  you need to make it as a culture for yourself to also start somewhere to start writing documentation
[18:15.200 --> 18:23.840]  and then it will somehow become a habit. So, thank you so much. This is all. You can all
[18:23.840 --> 18:29.440]  join the Pi Berlin Meetup in Berlin. You're all welcome to come. We have meetings every month.
[18:29.440 --> 18:45.360]  And also, some of the more articles about documentation you can read over there.
[18:45.360 --> 18:58.320]  Thank you, Anastasia. We have five minutes for questions. If we have questions,
[18:59.920 --> 19:03.680]  just raise your hand. Yeah, I'll pass the microphone so we can record the questions.
[19:04.320 --> 19:06.560]  Can you maybe pass it over?
[19:06.560 --> 19:20.960]  Thanks for the talk. Did you experience an increase in your documentation quality when using such
[19:20.960 --> 19:26.720]  tools? I mean, so the overall problem is you actually need to write documentation and you
[19:26.720 --> 19:32.960]  need like an incentive for it, right? Did you experience that using the tools that you presented
[19:32.960 --> 19:40.560]  helps? Well, it did help. So, we forced a certain documentation level. You can also see the tools
[19:40.560 --> 19:46.080]  that I used on the CI, on the project that I shared. They just did help to force people to
[19:46.080 --> 19:52.960]  write it. But actually, as soon as we made this as a must to have for every code review,
[19:52.960 --> 19:58.080]  then it helped. So, for every code review, every developer was looking, okay, you didn't write this
[19:58.080 --> 20:03.200]  documentation. This is important. And then they would ask, can you please write some few lines
[20:03.200 --> 20:12.160]  about this? This is important to remember. Then it did work. Thank you for the talk.
[20:13.760 --> 20:21.760]  I want you to ask about your opinion on using chat GPT to maybe ease the work of documentation,
[20:21.760 --> 20:27.520]  save your time if you've got any opinion on it. Because from my experimenting, it can document
[20:27.520 --> 20:33.600]  codaled like quite decently. So, maybe it could even be used for the tutorial based approach that
[20:33.600 --> 20:41.040]  you mentioned. Oh, actually, I didn't try it. So, I can try and let you know next time. Thanks.
[20:41.040 --> 20:54.800]  Any other question? Any other question?
[20:54.800 --> 21:16.800]  Hello. Thank you for your talk. Do you use restructured text, markdown? Do you think
[21:17.440 --> 21:20.400]  Python coders should use one or the other? Does it matter?
[21:20.400 --> 21:27.120]  Can you talk a bit louder? RST or MD? Which do you like?
[21:28.560 --> 21:32.240]  Well, it doesn't matter if you don't write documentation. So, it's important to actually
[21:32.240 --> 21:37.840]  write. And it's actually up to developers. Sometimes they like one, sometimes like the other.
[21:37.840 --> 21:51.200]  And I don't mind both. I just want to make sure that there is up-to-date documentation.
[21:52.720 --> 21:57.200]  Do you have actually tools to help you to make documentation up-to-date?
[21:58.880 --> 22:05.120]  Oh, that's a tricky question. Well, this is more like a human factor, how to make
[22:05.120 --> 22:11.040]  documentation up-to-date. You can test examples. You can even try the examples if they work.
[22:11.040 --> 22:16.240]  So, you can automate that. You can check how many lines of the documentation are in every
[22:16.240 --> 22:23.040]  request. So, this is automated. But it doesn't automate the things which are outside of the
[22:23.040 --> 22:26.960]  code. You cannot really test those. Unless there is a piece of code, you can go through it. You
[22:26.960 --> 22:34.480]  can try running it. So, unfortunately, the things outside of the very specific code, then this is,
[22:34.480 --> 22:36.560]  yeah, basically not. Thank you.
[22:41.360 --> 22:46.000]  Okay, we have two more minutes for questions. I see a question in the back. Perfect. I needed
[22:46.000 --> 23:02.160]  to do some support today. A, thank you for your talk. Is writing documentation something that you
[23:02.160 --> 23:09.280]  do alone or something that you collaborate with someone else? And if so, are there like
[23:09.280 --> 23:14.960]  non-technical people that collaborate with you in the moment of writing? Or how can you be sure to
[23:14.960 --> 23:21.760]  address also people with different levels of technical knowledge? Thank you.
[23:22.640 --> 23:27.200]  Thank you for the question. Actually, those are different types of documentation. So,
[23:27.200 --> 23:31.680]  there is a technical documentation which could be written by a technical writer.
[23:32.240 --> 23:38.800]  But the documentation that my team is writing, for example, should be written by a developer
[23:38.800 --> 23:44.240]  who is writing the code. So, your developer, you wrote a piece of code, a function, something
[23:44.240 --> 23:49.440]  you have to document it. And this is actually written in our ways of working for the team.
[23:49.440 --> 23:56.640]  So, that is part of the done of the features. So, as soon as this is done, it has to be
[23:56.640 --> 24:03.760]  documented. Unless it's documented, we don't close the ticket. So, it's have to have to happen.
[24:04.640 --> 24:09.520]  And this is for everyone in the team. So, there's no specific person on the developer who did the
[24:09.520 --> 24:15.760]  feature. Then they do it. Do we have any other question?
[24:19.520 --> 24:24.240]  Okay. Regarding chat GPT, I played a bit with it. I have the feeling like it's a great tool for
[24:24.240 --> 24:30.240]  beginners to learn. But if chat GPT can document it, then why should you? Shouldn't you put what
[24:30.240 --> 24:35.360]  chat GPT cannot guess from the code? All the business logic, the reasons you did it.
[24:35.360 --> 24:41.120]  It's just a small thinking. Thanks a lot, Anastasia. Thanks again.
[24:41.120 --> 25:06.240]  Thank you.