Contemporary Documentation – Django Day Copenhagen 2020

Hey Pat. Hey

Speaker 1: Demar. Hello, hello. How's it going? Great. Thank you for joining. Um so I have a a little quote that's by you. I hope uh it's uh open source. Uh you wrote in your description of the talk. Uh and and uh your talk is about documentation Um teams often change. People leave and people join. In addition to those changes, we tend to forget that what we were thinking That's why it's good practice to document those thoughts, discussions and decisions into a form and that doesn't lose them. So I guess we're gonna learn something more about those contemporary formats of uh of documenting so that we don't lose those thoughts.

Speaker 1: Um and uh I'm very much looking forward to what you're gonna be sharing now Um and I'll see you in a bit.

Speaker 2: Awesome. Alright, hello everybody. I'm US calling in from Helsinki, Finland. It's super nice to be part of the the Jungno Day event. I was really hoping to be there in person, but life happens and I guess we have to do the best with what we got. So instead I'm gonna Gonna join from Link. And when the world is a little bit plus, I'll definitely come visit and hopefully we can get some drinks together.

Speaker 2: So today we're gonna talk about documentation. And it's something that's really close to my heart as I've been working in different kinds of settings. And I've seen it firsthand how difficult it can be, especially for somebody joining the team, when things are not documented and it's difficult to find out who actually knows. About the things that you're working with. But I guess it's important to start with definitions Especially in this kind of case, because I don't think a lot of you have encountered contemporary documentation. It's kind of a a name that I came up with. When I was making this talk last last fall

Speaker 2: actually. And if we look at the dictionary definition of this, we can see That it's it's really vague. It captures both the history and the present. So it's basically contemporary is everything but the future. But in the context of documentation, we're gonna disregard the second part. And we're gonna focus on documentation that captures the moment and the context in history. During the time when decisions are made, discussions are had, and something that we quite often lose when time goes on To give a little bit of background of

Speaker 2: myself. Like I said, I'm Yohis coming in from Helsinki. I'm currently working as a developer advocate. At a company called Futuries, I run a couple of other developer communities as well. And what really sparked the interest for this dog. Is that I've been working in fast-growing, quite early-stage startups, as well as as a software consultant. And from both of these, I saw the same things over and over again. No matter what the company, no matter what kind of project or product. Every now and then these kind of

Speaker 2: problems would pop up and arise. And something that's that's especially common in fast-growing startups As in software consultancy, is that teams change. New people come in, old people leave. The current tenure of career in a single workplace is getting shorter and shorter And then it's it's kind of magnified in the context of startups where the startups might not be around for very long. And it's even more common that people Move around, switch companies, and change projects that they work on.

Speaker 2: And then on the other side, on the software consultancy When we work with the clients, basically people change, consultants change. Even the company that the client buys the project from might change in the middle And this is why we need to be really good at writing documentation. Because that's the only way we can build knowledge into the software project. Before I go into the contemporary side, one thing I want to highlight about documentation in general, regardless of what kind of documentation it is. Is that it should provide context.

Speaker 2: It shouldn't just tell you what it does or how it works. But especially why it was decided to build like this. We often make decisions that are imperfect We basically only make imperfect decisions because the situation at hand sets up restrictions of reality. So we always have to make trade-offs And we always have to make decisions based on the best knowledge that we have at the moment. And if we fail to capture the context of these things. We lose a lot of information that can become extremely costly

Speaker 2: in the life cycle of a software project And why I specifically chose to talk about the contemporary side is that most of the documentation that we have It's up to date and we need it to be up to date. Nobody wants to see a repository readme API docs. Or code comments, especially that are out of date and that are incorrect. So we need to keep most of the documentation up to date. But when we update everything all the time, it means that the documentation only

Speaker 2: contains The kind of latest things that we have. It only contains the current moment. And as human beings, we are quite good at knowing the current We can keep the latest couple of months in our head. And especially when we're working on a project, we know the ins and outs of that project So that's kind of enough in many cases. But then there's a lot of cases where we end up making decisions today, and two years down the line. We have to make a change or something broke. And if we don't know

Speaker 2: why it was built the way it was, it's really difficult for us to know. If we're gonna cause more problems. And that's something I'm especially gonna talk about in the contemporary side. And one of the things is that documentation is something that it sparks up a lot of discussion As I've been giving this talk here and there, there's been a lot of discussion after the talk. Really strong opinions that people have for and against different aspects of documentation. And I want to emphasize that I'm not here to tell you the right way. I'm here to give you some ideas, some new ways of thinking, how you can capture the

Speaker 2: moment in history. So that the future you and the future teammates can have an easier time figuring out what's happening. Could split the idea of contemporary documentation into three branches. And the idea here is that I'm using the tools and technologies and methodologies that many of you are already using I don't want to introduce a new tool that you need to get the buy-in and you need to kind of change the way you work. The idea of contemporary documentation, as I see it is to be an incremental improvement

Speaker 2: over something that you do right now. And The lingua franca that I'm gonna use comes from the Git ecosystem. But if you're using something similar but different, I hope you can kind of get the mental idea Of these tools and match that into what you already use. So today we're gonna talk about the commit messages or something similar, something where you track down. The kind of context and history of individual changes. We're gonna talk about the code review Whatever way you happen to use it, whether it's

Speaker 2: git up and pull requests, or whether it's using email notes. And patch files. But I hope that many of you are doing some kind of code review in your teams. And then last We're gonna talk about stories, tasks, tickets, puck reports, whatever you call them. I affectionately call them Chira tickets, because I've been working with Chira quite a lot lately. And the idea is that these are the things that a lot of developers use these days. And by make using them little bit differently. And more importantly, expanding the way we use them.

Speaker 2: We can capture the moment in history and help the future of us be better at what we do. Documentation, however, is not easy. And I think there's a couple of reasons why it's not easy for us as engineers. I think the first reason is that we aren't taught documentation. It's been a while since I've been studying, but at least during my time. We didn't have a course on documentation. We had to cut over the report. on some of the things we did, but that was more of an academic writing exercise

Speaker 2: than actual software documentation. Instead we are trained to write for the computers to understand. So it can be challenging to write for other people. And the second reason it's difficult is that as human beings, especially in the era Of constant connection, social media. We are not very good with delayed gratification. And with documentation the thing is that the gratification might never come To the person who wrote the documentation. It might be that you're out of the company before that piece of documentation is ever needed.

Speaker 2: So we need to kind of motivate ourselves some other way than getting the instant gratification and the aid of dopamine when we write documentation And that's why I I'm not advising you to completely change everything you do Don't go into the history and try to change your commit messages and pull requests. And don't try to do everything at once. If you take one idea from today and improve that in your day to day with like ten percent or even one percent Over time that change will grow and it will save you time. Alright, let's get into the

Speaker 2: meat of the talk. Let's start from comment messages. I personally use a lot of kit. I've been using kit all my professional life. And Writing commit messages is something that once again never was actually taught to me. It's something I learned by doing and especially learned by reading other people's commit messages. And whenever I talk about commit messages, I I need to show this. A classic comic By the XKCD, because this is such a good representation, and I'm the first one to admit I'm guilty of this as well When we start working on something, whether it's the start of the project, start of the week, start of the day.

Speaker 2: Sort of a feature. It's easier to have the energy to be pedantic and to write good commit messages and think about how to tell what I'm doing. But as time goes on, we get tired. Maybe there's pressure from from your team. Maybe there's a deadline. Maybe there's a product owner who needed the feature yesterday and then the quality of your commit messages starts to decrease. And I think we can all agree that some of the latest commit messages in this example are not useful to anybody.

Speaker 2: After the fact, if I go back to the code and I see more code, that's not particularly gonna help me do my thing And there's a great way to kind of think about what you want to write. And this is the question that kind of sparked my interest to talk about this topic and to write about this topic. And it is, what would you like to know two years from now? What are the things that are obvious to you now? Because you've been so deep in thought and so deep into the code base and the feature that you take them for granted. They're obvious for you.

Speaker 2: And because it's difficult to think what I need two years from now, I often rephrase it with what would I need to ask? What are the pitfalls that I could face with this change in code? And I try to ask this question. Because the thing is that in two years you're not gonna remember What you were working on. And quite likely you're not gonna be in that project anymore. There's a really great example. I will share all these slides. You can find them on my Twitter as well. This is from a a UK government project and this is a really great example. Not all the commit messages need to be this complex.

Speaker 2: But the thing with commit messages is that text is cheap when stored. You can write more than just a one-liner You can explain what you did, what you tried, what was the solution. And especially for the the tricky things, the things that you had to spend some time figuring it out. This is a really great way to capture that so that people can find it when they run into the same problem or they need to change something related to this code So capturing those kind of obvious things that you wouldn't think about otherwise into a commit message

Speaker 2: can be a really helpful thing in capturing the moment. This is not something that you would keep in an up-to-date documentation because these kind of things happen a lot. But in the comment history, it can be a really great place. The second thing is the gold reviews. Code reviews are something that I'm passionate about, all in all in general, and I could talk for hours about how I find them extremely valuable. Not as a duel of judgment, but a duel of sharing knowledge, learning, teaching, and helping people get into the shared

Speaker 2: code base But today I want to talk about them from the perspective of documentation. In my workflow, the code review usually means a GitHub pull request But the same kind of basics apply to all different ways that you want to do code review. The first and most important thing is to write things down. I know a lot of developers like have code reviews sitting down with somebody or during this time jumping on a June call and talking it through. Having a discussion. And that's great if you do that. I think that's a really good way to go through changes.

Speaker 2: But you should always write it down Whatever discussions you have, whatever ideas come up, whatever questions arise, because those discussions, they're gonna disappear. I don't remember the discussions I had with my colleague this week on Monday. So write it down immediately after. Not at the end of the day. Not at the end of the week. But right after you add those discussion. And go preview is a great place to ask a lot of questions It's not a one-way street where you submit something to somebody else to judge and review, but it's a two-way street

Speaker 2: You can drive the code review and the discussion as well as an author. And once you have made some comments and you end up making changes, Don't delete those comments. Keep the history. Because often we make decisions not to do something. And knowing that is valuable. But it's not something we usually write down. And then the third part is stories, tasks, tickets. Whatever you use to record what you need to do beforehand. One of the things I often recommend writing down is the origin and the business driver.

Speaker 2: Of a particular change. Why is it important to make this change? Because the situation might change. And in the future, if you need to change something in the code and you don't know why it was made originally, it can cause a lot of problems. Because it might break something that's undocumented. Especially for bugs. This comes in the form of how to reproduce the bug. Accompanied with disks, that's a great way to make sure that we don't introduce it again. Having some sort of definition of done Because things change gradually, little by little, part

Speaker 2: by part. So it's valuable to know when this particular ticket was done. Just like Gold Review, this is a great place to ask a lot of questions. You can ask questions from the business people. Your teammates, the end users, whoever is relevant to that piece of code and that piece of functionality. Because they are the people who you often know best. what they actually need and what they actually want. And the thing with these discussions is that these are often had somewhere outside the platform. I haven't seen a lot of places where the business people

Speaker 2: would write comments on Jira or the GitHub issues. So you often end up having these discussions over a meeting. Or casually on the the hallway. Write it down. All the questions and the answers need to be documented. Or otherwise they're lost knowledge. Because in two years, you're not gonna remember those discussions. And you probably won't be in that project anymore So write the things down. That's kind of how documentation works in general. I wanna show a quick example of kind of the workflow. From the other side.

Speaker 2: When you have some documentation, this is what I do when I start working on a bug fix or a new feature And the example is really simplified, so don't look too much into the content of it. But I just want to show you, maybe give you ideas. Of how this kind of documentation can be valuable. Let's say I need to change something in this Python file And I find this some method which looks a little bit funny. This is not what I was taught in in elementary school, how to do math. But I need to change this

Speaker 2: because there's some new requirements. What I then do is that I use git plane And this isn't these days built into most of the code editors and ideas. And I can find the change and the commit that's responsible for it Using that commit hash, I can find it from GitHub. And by going into the commit where this change came from, I can find the commit message. I can find the changes, but I can also find where this change came from. Which pull request brought this commit? Into the code base. So

Speaker 2: clicking into the pull request, I can get into the code review. And this is not a good example of a great code review because there's no comments. But what it does have is that it has an integration saying that this fixes the ticket in the ticketing system. And if we click that, we end up In the the issue tracker or the ticket system, and we can find out the things that are relevant. What were the discussions? Now I can find out that That the company had chosen this particular method because they made a trade-off. It works with the Martian clients

Speaker 2: And if we need to bring in clients from other planets, then we need to change things. But if this gives me confidence to change this code, because I know what has happened before. So let's recap. Commit messages, code reviews, and issues are a great way to capture the moment in history. And not lose all that when the documentation changes. Think about what are the things that are obvious to you right now. But might grip you or your teammate in a couple of years. And finally, and maybe most importantly, write it

Speaker 2: down. In two years you're not gonna remember what you were thinking and discussing. And you probably won't, Peter. Thanks for having me! I will be happy to take some questions. I will also be available on on Julip today to to hear about your ideas, your thoughts about this kind of thing. And I'm I'm looking forward for the the next talks as well.

Speaker 1: Thank you so so much, Yuis. Can you hear me?

Speaker 2: Yes.

Speaker 1: Amazing. We have a question from the internet and I'm gonna read it out. It's a question from uh from Peter on Sullib. He asks in our team we always write it down and he's saying that with a big smiley. So

Speaker 2: that's right.

Speaker 1: Both during code review and also for issues, tasks, bugs, etc. But we often run into difficulty to find things later. Like we remember discussing something many months ago, but the relevant issues slash merge requests etc along closed and filed away. The tools don't seem to offer a good way to locate past information slash discussions. Do you have any experience with that or any suggestions?

Speaker 2: Yeah, so the first thing for that is the kind of workflow that I showed. It's not especially good for kind of searching with a certain text, but sometimes it can help you. If your starting point is the code. Other than that , like it's it's a really nasty issue that we have as kind of the world is that finding knowledge from the knowledge bases that we have. Whether it's these kind of things that I took today, whether it's intranet, it's it's still really difficult challenge. And I don't have like a silver bullet, but one thing that I'm I'm quite excited about

Speaker 2: is the work that companies are doing to bring different kinds of machine learning tools To help find information from this kind of like unstructured data. It's something that some of my colleagues are doing. Really cool things inside the company. Helping us find the kind of hidden information, especially the type of things that we don't even know that we we wrote down in a way. Finding connections between things and and so on. I do feel that for example GitHub has quite good tools for searching things. It's not perfect. And the difficulty of course

Speaker 2: is that if if you use different tools for different things, you don't have like a single place to search. But one thing that I recommend is maintaining good links between things. So In your pull requests, you should always link to the ticket that it solves. Because then it it's enough to find one piece of the puzzle. And you can follow the links different directions.

Speaker 1: So when you have

Speaker 2: that kind of answer something.

Speaker 1: Yeah, it's it's very valuable like when you have a lot of different places for information and it you cannot uh remember by hard where some something went make use of the crosslings as much as as as possible Um let's see. I have a question uh for myself. Um I'm wondering when writing it down uh if I can uh become better at uh writing it down not just for the benefit of of others and future and so on but actually immediately to benefit from it by incorporating this in my own understanding of the problem and and the solution, if that's also uh an aspect of these uh

Speaker 1: three branches.

Speaker 2: I think it definitely is. All the writing we do helps us become better at writing, but it also helps us understand things like you said. I I think that teaching is the best way to learn. Because when you tell somebody else something, or when you write it down, you have to think about it From little bit different angles. You you think about things a little bit differently than you write. So it kind of forces you To think things from different perspectives. And that's always helpful for making sure that you understand it better And you also remember it better. So definitely yes.

Speaker 1: Write it down. I hope this uh echoes around uh to a lot of people, both people building stuff at companies for their colleagues, but certainly also those building uh reusable software who may may never be uh in touch with the others that uh that have to understand their decisions.

Speaker 2: And it's it's definitely something that kind of also needs the drive from the business side You know and like we need to understand as companies the value of documentation. It's it's unfortunately often seen as kind of wasted time. Because it's difficult to measure the costs of not documenting. Especially because it happens later. So I hope that It's so also inspiring. Enough people can decide how to use the time in your software projects

Speaker 1: Thank you so so much for joining Uis. Um Thanks

Speaker 2: very much

Speaker 1: um yeah We'll be in touch on Sullib, writing things down, writing questions down for you maybe. Um let's give a big hand for you.