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 | 542 | |
| Author | ||
| Contributors | ||
| License | CC Attribution 2.0 Belgium: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor. | |
| Identifiers | 10.5446/62026 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
00:00
SoftwareSelf-organizationAssociative propertySoftware developerWordComputer animation
01:01
Digital photographyMachine codeMachine codeFormal languageComputer programmingComputer animation
02:29
SynchronizationRootMachine codeDigital photographyOpen sourceDirection (geometry)Series (mathematics)Menu (computing)Confidence intervalWritingSoftware developerLatent heatVideo gameMachine codeElectronic program guideBitDirection (geometry)Set (mathematics)MereologyInformationFunctional (mathematics)Computer fileParameter (computer programming)Computer-assisted translationResultantComputer programmingAnalytic continuationPoint (geometry)Open sourceTelecommunicationDifferent (Kate Ryan album)String (computer science)Web 2.0Computer animation
10:00
Open sourceMachine codeDigital photographyModule (mathematics)Function (mathematics)GoogolMaxima and minimaPhysical lawInclusion mapSoftware developerBlogDifferent (Kate Ryan album)1 (number)Machine codeResultantComputer-assisted translationOpen sourceKey (cryptography)Set (mathematics)BitType theoryElectronic program guideFunctional (mathematics)Projective planeWeb pageLevel (video gaming)SoftwareSheaf (mathematics)Revision controlComputer animation
17:32
Normed vector spaceDigital photographyMachine codePrice indexTable (information)Forcing (mathematics)Lattice (order)Level (video gaming)BitLink (knot theory)Reading (process)Set (mathematics)Software developerMachine codeProjective planeDifferent (Kate Ryan album)MereologyPerfect groupMoment (mathematics)Type theoryMultiplication signLine (geometry)WritingComputer animation
24:47
Program flowchart
Transcript: English(auto-generated)
00:05
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.
00:21
And I play a role as an associate director of engineering at Soundwide in Berlin. Also, I'm one of the organizers of PyBerlinMIDAP. 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.
00:41
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.
01:02
Do you document your code? So raise a hand if you do write documentation. Oh, wow, a lot. Nice. OK. That's very nice. So some years ago, around 10 years ago,
01:21
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 the Hello World program. It was very nice. It looked so perfect. I did a first pull request into our code.
01:41
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,
02:00
or somebody will just change that 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.
02:21
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.
02:43
So 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 an open source developer
03:02
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.
03:22
I would not do so many mistakes as I did through all the years. And that's why we're here. I'm gonna 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.
03:45
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,
04:02
very little, wondering, wondering, why am I so sad? Why no one is talking to me? And had no clue how to deal with other services, other developers, and had so many questions in its lifetime, and the only sad cat
04:21
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.
04:42
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,
05:01
what is the purpose, also names of the parameters where they lost at some point. So you remember the story, there was a set code, very sad code, and just the cat sitting next to the set code, and the code went to sleep, and something truly magical happened.
05:22
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.
05:41
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 set code said, please continue.
06:00
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,
06:20
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 in basically everything written about the code. It includes a recipe or the direction
06:41
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 how-to guide, but something how to create for a very specific reason.
07:01
That would be a how-to guide, and those are actually very specific guidelines that we are usually looking for because we have all 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,
07:22
the set code was thinking, okay, I can improve by just writing a simple setup, how to set up myself to be open for others, so that's very specific, what to install, where to install, and added some README file to the guideline of the code.
07:44
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.
08:02
So the second advice showed 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,
08:21
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're talking about the code, then just follow the advices. Also would be learning by doing, writing some specific tutorials
08:44
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 string setup,
09:03
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
09:23
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,
09:45
those 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,
10:01
or which ingredients are particular for a very specific dish. This is everything that could tell the said little code how to deal with different packages or different services, how to integrate with others, and of course, the set code
10:21
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.
10:41
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 APIs,
11:01
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.
11:24
And just like that, the set code followed the fourth piece of advice and decided to write the code reference, edit that, and also applaud that to somewhere for others to see.
11:43
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,
12:00
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's the riddle? So here it is. I'm someone who can teach you a lesson, but not a teacher.
12:23
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. I'm someone who can explain you a particular topic to help you to understand, but not Google.
12:43
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,
13:01
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 and your future, I'm your future, fantastic documentation, with the tutorials, how-to guides, explanation, and the references.
13:23
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
13:40
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,
14:02
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.
14:21
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,
14:43
I have a few more pieces of advices 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,
15:00
or maybe something happens and then, well you return back to the code and then you don't remember why 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,
15:20
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,
15:41
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.
16:01
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 where to put documentation about the legacy code,
16:21
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 would be like a next level.
16:43
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 docstrings 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,
17:00
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 that 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.
17:21
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,
17:41
so this is how the read the docs would look if you would use it for a simpler project, and this is how the Sphinx of the 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,
18:02
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.
18:21
So, thank you so much. This is all. You can all join the PyBerlin 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.
18:54
Thank you, Anastasia. We have five minutes for questions. If we have questions, just raise your hand.
19:01
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?
19:22
I mean, so the overall problem is you actually need to write documentation and you need an incentive for it, right? Did you experience that using the tools that you presented helped? Well, it did help. So, we forced a certain documentation level. You can also see the tools that I used on the CI
19:42
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,
20:01
can you please write a 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 JetGPT to maybe ease the work of documentation,
20:22
save your time if you've got any opinion on it, because from my experimenting, it can document code 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.
20:41
Thanks. Any other question?
21:06
Next speaker. Oh, you have a question. Hello, thank you for your talk. Do you use restructure text, markdown? Do you think Python coders should use one or the other?
21:20
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. Some teams, they like one, some teams like the other, and I don't mind both.
21:40
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.
22:02
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 pull request, so this is automated, but it doesn't automate the things
22:21
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.
22:41
Okay, we have two more minutes for questions. Ah, I see a question in the back, perfect. I needed to do some sport today. Hey, thank you for your talk. Is writing documentation something that you do alone,
23:04
or something that you collaborate with someone else? And if so, are there 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?
23:22
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 documentation that my team is writing, for example, should be written by a developer who is writing the code.
23:40
So, you're a 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,
24:01
so it's have to happen. And this is for everyone in the team. So, there's no specific person, only developer who did the feature, then they do it. Do we have any other question? Okay, regarding Chudge GPT, I played a bit with it.
24:22
I have the feeling like it's a great tool for beginners to learn, but if Chudge GPT can document it, then why should you? Shouldn't you put what Chudge GPT cannot guess from the code, all the business logic, the reasons you did it? Just a small thinking. Thanks a lot, Anastasia, thanks again.
24:42
Thank you.