So, hello everyone. My name is Anastasia and I can say a few words about myself before
we start today's talk. I came here from Berlin. I live in Germany, Berlin, for already seven
years but I'm from Ukraine originally and I play a role as an associate director of
engineering at SoundWide in Berlin. Also, I'm one of the organizers of PyBerlin Meetup and I have
11 years of experience in software development and seven of them in Python. You can see how happy
I am with Python and I can share and I will share my long road to programming actually with
documentation and you will learn from me what I learned through all the years of software
development. And let's start today's talk with a question. Do you document your code? So,
rise a hand if you do, write documentation. Wow, a lot. Nice. Okay. That's very nice. So,
some years ago, around 10 years ago, when I just started, I remember myself, I started
programming language. I took a programming book, then I just went by the book. I wrote a
Hello World program. It was very nice. It looked so perfect. I did the first pull request into
our code and I thought it was very perfect. It looked so great. It was approved but it didn't
feel right. I didn't even know what to check but I just didn't feel right and I was not sure
would this code still be live or there in some years or maybe in six months or somebody will
just change the code and then it would be not good anymore. And when I even passed the code
review, I merged the code. I was still not sure what to check in the code and when to consider
that the code is good enough. And of course, I didn't know about documentation. I was not told
that I should write documentation in my code. And today, we're going to look into the 10 years
after I started. So, after all of this time, I realized that experience comes together with
the confidence of you more. You are more confident in the code that you're writing because you're
writing a lot and then you learn from other people. You go to the conferences. You listen
to all the talks, all the experiences. You talk to other developers in the community. If you're
open source developer and there is no documentation, it's a bit tricky. So, what if me 10 years ago
could possibly travel into the future and listen to this talk and know what to do from the very
start? I would be maybe happier in my life. I would not do so many mistakes as I did through
all the years. And that's why we're here. I'm going to show you things that I learned over the years
and we are going to have a bit of a magic today happening following the 10 years into the future.
So, let the future begin now. Let's start with the story of one little set code
which was lost in its lifetime and no one wanted to play with this code. This is the code that I'm
talking about. And the code was just sitting there very sad, very little, wondering why am I so sad,
why no one is talking to me. And had no clue how to deal with other services or other developers
and had so many questions in its lifetime. And the only sad cat was sitting and supporting that
set code. So, the set code was actually wondering what is wrong with it and how to change to find
new friends. Let's take a look into the code. So, the first function, it's pretty clear. It's just
the hello world, the basic stuff. But if you look to the second one, this is the sad part.
So, there is a function with some of the arguments and some of the results returning something but
not very clear, not very clear the outcome of the function, what does it do, what is the purpose,
also names of the parameters where they lost at some point. So, you remember the story,
there was a sad code, very sad code, and just the cat sitting next to the sad code. And the code
went to sleep. And something truly magical happened. It met someone. It met its future self,
just right 10 years after. And the future self said, I will give you four pieces of advice
which will help you to improve your communication skills. And in the end,
I will give you a riddle to solve. So, follow my advice to reclaim the ancient knowledge
of programming superpowers and you will shine for many, many years.
So, let's start. Then listen carefully. Yes, the sad code said, please continue. So,
here is my first advice to you. This is the way how to use the goal oriented approach
to show the world how to solve a problem if there are any in the future. This approach is about
writing how-to guides. So, those are basically the directions to the reader and you can read
a bit more in the links which I listed over there. This is the most used guide, the most searched
and the most read and basically everything written about the code. It includes like a recipe
or the direction for solving a very specific problem. So, if you are trying to create something
of the how-to guide about something very specific, not very about everything like how to create a
web server, something that would not be a how-to guide, but something how-to create for a very
specific reason. That would be a how-to guide and those are actually very specific guidelines
that we are usually looking for because we have all of the specific issues and then we are searching
for a specific piece of information for a specific problem as a solution.
So, with the first piece of advice, the set code was thinking, okay, I can improve by just writing
a simple set up, how to set up myself to be open for others. So, that's a very specific
what to install, where to install and added some read me file to the guideline of the code.
And then, after following that advice, the set code noticed that they got a friend. Can you
imagine? A friend, a real friend. How do I know that? Well, just look at that. There is a star
shining. Well, that was just the start, the first one. So, the second advice show the set code how
to use learning oriented approach to show the world what actually is done by this code. So,
those are the tutorials. Those are a bit different from the how-to guides in the way that this is
more like learning by doing. So, you are not reading all the documentation. You are just
doing an exercise like a teacher showing in the school what to do to learn a specific subject.
So, if we are talking about the code, then just follow the advices also would be learning by
doing, writing some specific tutorials would be to achieve some goal, but it doesn't have to be a
very specific problem to be solved. So, if we are following the advice, the set code was thinking,
okay, maybe I can add a bit more. Let me write some tutorial about basic things set up, how to
write it, how to build it, and then something happened again. There was another friend. Look
at that. The second star is shining. Already good. Good path. The third advice showed the set code
how to use understanding oriented approach to explain more what the code is doing. So,
those are the explanations, different discussions on very specific topics which are
broadening the main subject. So, if we already have the basic documentation, we have the how-to
guides, we have different learning by doing exercises. Those are explanations are very,
very specific. So, if you compare to a recipe book, this is not a recipe book. This is more of a
reference of the different ingredients, how to get the ingredient, for example, or which
ingredients are particular for a very specific dish. This is everything that could tell the
said little code how to do with different packages or different services, how to integrate with
others. And, of course, the set code did implement something like this. So, they wrote a bit of
more explanation on why do we need documentation in general. And, again, it was very helpful,
very happy. So, the set code was thinking, okay, and more friends are coming. That's great.
Let's go to the last advice. So, the last but not least piece of advice was about information
oriented approach, about references. In software development, reference guides are usually describing
the functions, the input, output, arguments, the results of the functions, key classes,
different API. So, everything that is about the code, about different attributes, it doesn't
have to be every single function, but it should be all of the main key classes, key functions that
are used. So, then, afterwards, you can recap and then look just the 10 years after you can look
at what was done before. And, just like that, the set code followed the fourth piece of advice
and decided to write a code reference, added that, and also applaud that to somewhere for others to
see. And, after those four wonderful advices from the future self, something really magic happened.
The code woke up, not very sad anymore, not mad, and it felt very comfortable to go out and then
talk to others, connect to other developers. And, then, after some time, the set code remembered
that there was a riddle, the future self said there would be a riddle, and then you will
gain the superpowers, right, where is the riddle. So, 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 aspects of your functions,
but not an encyclopedia. I'm someone who can explain you a particular topic to help you to
understand, but not Google. Can you guess what that is? Okay. So, the code was very happy because
they knew the answer already and asked the future self, so, well, look, was it all about you? All
about you, my future. So, you are documentation. So, you are really my future. And, the future
self said, yes, those four advices were all about me. I'm your future. I'm your future. Fantastic
documentation with the tutorials, how to guides, explanation, and the references.
And, in other words, we all need to understand that documentation is not a single piece.
It's more than that. It consists of four different types of documentation, and it's very important
that we add all of them, and we at least have some sections of those to focus for our future
selves, not to be in trouble. So, just to recap the future of that little code is now, it's about
code references, tutorials, explanations, how to guides, and that would make your code happy,
and the cat, of course. And, it would get many friends, especially in open source, it's very
important to add documentation and to explain what is code actually doing and all the functions.
And, that would be a really bright future. So, I have another question for all of you. Would
you document your code after all of you heard in the future? So, if this example didn't convince
you, I have a few more pieces of advice from myself, from my own experience, why do we need
to document code? Because people forget things. Even if you wrote the code, you will forget about
it in a week, in a month, in a day, or maybe something happens, and then, well, you return
back to the code and then you don't remember why it was it. People leave the code alone,
and this is also important. If you are working for open source, you can give it to somebody else,
you leave it alone, then you come back, you need to review, and then, oh my God, I didn't
remember that function. Then, new people come to contribute. This is also very important. They
need to know how to contribute, what to contribute, what is important for this. So, how to start?
First, you need to choose, you need to choose main source tool for documentation,
and then, of course, you need to make sure that it's up to date. So, the continuous documentation,
it's a culture. It's not the thing that you can force people into. You need to make it as a culture
for yourself and also for other people. So, I would recommend you to read a few things.
This was the original document where it's actually written about those four pieces of
documentation. I recommend you to go through it, read more about different types of documentation,
then also what are the documentation about the legacy code, and the real Python has a very
nice tutorial about documentation with MK docs and also GitHub pages. So, how to start? You need
to start as simple as possible. This is the best solution. Just start some basics. Then, you can
go to version control documentation, and that will be like a next level. So, you have Python code,
you need to document something. First, what do you do? I would say you start documenting. So,
for that, you need to add some doc strings to your code, then you will take them and then make a
reference guide, which is already nice to have. It's out of the box. It can be auto-generated if
you host it somewhere so beautiful and easy. And for that, you can use Sphinx MK docs to prepare
the documentation, also put some files. And, of course, you can try to host it somewhere
like read the docs, which is free for open source projects or GitHub pages. Well, there are other
tools, but those are the ones I used. And, of course, add more documentation. So, if you want to see
those pieces of documentation that I showed, here is the link where they are. And also, you can
see in here, so this is how the read the docs would look if you would use it for a simple project.
And this is how the Sphinx documentation that I showed you with the set code would look like.
And to then just to remind you that you cannot force people to read documentation. You can force
them only to write documentation. So, if you want to make sure that your documentation is up to date,
you need to make it as a culture for yourself to also start somewhere to start writing documentation
and then it will somehow become a habit. So, thank you so much. This is all. You can all
join the Pi Berlin Meetup in Berlin. You're all welcome to come. We have meetings every month.
And also, some of the more articles about documentation you can read over there.
Thank you, Anastasia. We have five minutes for questions. If we have questions,
just raise your hand. Yeah, I'll pass the microphone so we can record the questions.
Can you maybe pass it over?
Thanks for the talk. Did you experience an increase in your documentation quality when using such
tools? I mean, so the overall problem is you actually need to write documentation and you
need like an incentive for it, right? Did you experience that using the tools that you presented
helps? Well, it did help. So, we forced a certain documentation level. You can also see the tools
that I used on the CI, on the project that I shared. They just did help to force people to
write it. But actually, as soon as we made this as a must to have for every code review,
then it helped. So, for every code review, every developer was looking, okay, you didn't write this
documentation. This is important. And then they would ask, can you please write some few lines
about this? This is important to remember. Then it did work. Thank you for the talk.
I want you to ask about your opinion on using chat GPT to maybe ease the work of documentation,
save your time if you've got any opinion on it. Because from my experimenting, it can document
codaled like quite decently. So, maybe it could even be used for the tutorial based approach that
you mentioned. Oh, actually, I didn't try it. So, I can try and let you know next time. Thanks.
Any other question? Any other question?
Hello. Thank you for your talk. Do you use restructured text, markdown? Do you think
Python coders should use one or the other? Does it matter?
Can you talk a bit louder? RST or MD? Which do you like?
Well, it doesn't matter if you don't write documentation. So, it's important to actually
write. And it's actually up to developers. Sometimes they like one, sometimes like the other.
And I don't mind both. I just want to make sure that there is up-to-date documentation.
Do you have actually tools to help you to make documentation up-to-date?
Oh, that's a tricky question. Well, this is more like a human factor, how to make
documentation up-to-date. You can test examples. You can even try the examples if they work.
So, you can automate that. You can check how many lines of the documentation are in every
request. So, this is automated. But it doesn't automate the things which are outside of the
code. You cannot really test those. Unless there is a piece of code, you can go through it. You
can try running it. So, unfortunately, the things outside of the very specific code, then this is,
yeah, basically not. Thank you.
Okay, we have two more minutes for questions. I see a question in the back. Perfect. I needed
to do some support today. A, thank you for your talk. Is writing documentation something that you
do alone or something that you collaborate with someone else? And if so, are there like
non-technical people that collaborate with you in the moment of writing? Or how can you be sure to
address also people with different levels of technical knowledge? Thank you.
Thank you for the question. Actually, those are different types of documentation. So,
there is a technical documentation which could be written by a technical writer.
But the documentation that my team is writing, for example, should be written by a developer
who is writing the code. So, your developer, you wrote a piece of code, a function, something
you have to document it. And this is actually written in our ways of working for the team.
So, that is part of the done of the features. So, as soon as this is done, it has to be
documented. Unless it's documented, we don't close the ticket. So, it's have to have to happen.
And this is for everyone in the team. So, there's no specific person on the developer who did the
feature. Then they do it. Do we have any other question?
Okay. Regarding chat GPT, I played a bit with it. I have the feeling like it's a great tool for
beginners to learn. But if chat GPT can document it, then why should you? Shouldn't you put what
chat GPT cannot guess from the code? All the business logic, the reasons you did it.
It's just a small thinking. Thanks a lot, Anastasia. Thanks again.
Thank you.