 Thank you for joining this session. My name is Omer and I'm really happy to be talking to you today about a topic that is close to my heart that I've been researching and working on for the past years called Continuous Documentation, but before we jump into continuous documentation. Let me take you just a few years back A few years ago. I was leading an international training program focused on cyber security and data science We were extremely privileged to have amazing students in this program. They were all brilliant people highly qualified graduates of top universities from around the globe and came with relevant job experience It was a real pleasure to teach them and after the program finished. I would keep in touch with those people I would talk to them and hear their experience as they started their new jobs Job that they would eventually become leaders in while talking to them I realized they keep hearing the same stories over and over again I hear them explaining how hard it is to get on boarded to a new code base or new code bases It's so many lines of code They said and all that logic Accumulating over time by people that some of them are still there on the team and some are no longer there There is complex logic to get grasp on with lots of decisions that have been made along the way It took time and effort from them and also from people who were with them on the team and got to know the code base better As they explained the code to the new hires even for those brilliant Skilled and experienced people the experience of being on boarded to a new code base is hard It takes time and effort and I kept hearing similar stories from other people around the industry in many different companies So getting on boarded to new code is hard, especially when you start your new job But does it end there? Is it the only time when you need to understand new code? Well as developers We know that not at all Understanding code happens all the time. It happens to us on a daily basis We always get tasks that involves looking at code that someone else has written It could be in a code part that is new to us It could be in a code part that we already contributed to but has changed since the last time we touched it We don't necessarily understand the motivation for the code that's there or all the details that were involved by when implementing it Sometimes we need to understand code right now. For example, there is a bug. It's affecting production It's affecting our clients. We need to find a solution right now and for that We're trying to look around we're reading the code We're asking people maybe someone knows this part of the code and sometimes in those magical times There is something there that helps us and that's a document and even a great document This document is there and it can help us in many ways It can describe the big picture for example telling us why this code is there and why it was constructed the way it is It can also provide us with some practical Specific implementation details that will help us a lot while we implement the solution But as we well know this reality doesn't always happen this document rarely exists a Document that is relevant rarely exists if it does exist We won't necessarily find it and sometimes we find a document that's supposed to help us just to find out That it's outdated that the code has evolved and changed so much since this document was written that it's just no longer helpful I Would like to argue that developers need and deserve good Documentation when such documentation exists. It helps in so many ways It helps developers on board to new code bases for example when they start a new job or switch between teams It helps teams be more flexible and inclusive as different team members can quickly get into new code parts and contribute to them It can also help you on those times when you need to find a solution Right now for example if there is a bug affecting production So it sounds easy, right? If we agree the developers and developer teams need and deserve good documentation Sounds like there is an easy solution we can do Let's all document and all will be better. Well in theory maybe but practically This is not the case. It sounds like a fantasy world and I would like to think why I mean after all Documentation can help in so many ways. So why don't we have good documentation? And when asking why I think as developers we've all been there. We've all started new jobs We've all been on the side that's supposed to create documentation and we don't always follow that So why does that happen? I? believe the problem is that Current practices and tools for creating and maintaining documentation simply don't serve developers as a result documentation is lacking or often outdated and Therefore developers may not rely on the documentation at all and not bother to create it and actually with the current tools that practices It kind of makes sense. I mean creating documentation Takes a lot of time and effort. It's hard to know where to start and It just takes a lot of your time and then let's say you took that time and you wrote the documentation Making sure that it is up to date is nearly impossible and you may stop and ask yourself Okay, I'm writing this document now, but it's going to become obsolete in a few hours weeks month Why even bother and spend all this time writing something that is going to become obsolete so fast? So we agree developers need good documentation developers deserve good documentation But the current tools and practices are broken and don't serve developers So I'd like to argue that code documentation Requires new methods and tools and I describe those methods in an article I wrote about continuous documentation that was published in info queue and got the name the continuous documentation Manifesto and I'd like to share with you its basic principles right now Continuous documentation calls for creating and maintaining documentation within the development workflow In other words treating your documentation as a crucial part of your development workflow like tests or the code itself It consists of three basic principles. So according to continuous documentation the documentation should be code couples Always up to date and Created when best Let me just explain each one of these Code couple documentation means documentation that explicitly references parts of the code base Let's examine a simplified tutorial of how to add a command to git's code base So here for example We explain how to add a command to git in this example We show the command ad that is git ad so the document explains that every command has a file with a corresponding name Within the built-in folder in this example. It's add dot C This file includes the definition of the command in this case cmd add for command add as we can see here within the code of add dot C It goes on to explain that the function must be declared within built-in dot H And here we can see its declaration within built-in dot H in addition to make you the wear of the add command It needs to be registered by adding a cmd struct to the command array as we can see right here within git dot C What makes this document code coupled well? It includes text just like any other document, but it also includes explicit references to the code for example Here we can see a snippet actual lines of code from the code base It can also include a path for example here. It's a folder. It can also be a filename It can also include names for example here We can see a functions name or it could be a variables name all in all It's references of parts of the code base that are embedded within the text and within the document as a whole Code coupled documentation is great for many reasons It provides a standard to what documentation should look like what practical documentation for developers should look like And for me as a developer I'm really happy when I see this kind of document or tutorial when I see it I know it's gonna be practical for me It is going to help me understand what's happening in the code why it was implemented that way and what the actual state of the code is It is also much easier to create documentation that is code coupled as someone trying to create Documentation that is practical It's easier to start with a code base or specific parts of the code base and then explain what those parts do It's much easier than starting with say a blank page trying to think about what to write and then filling it up with words Code coupled documentation also enables many other things for example It's easier to find documentation this way and also it enables making sure the documents are always up to date Which leads me to the second principle of continuous documentation The documentation should always be up to date That means that we need to make sure that the current state of the documentation matches the current state of the code base as Developers we know that code changes it changes frequently it changes a lot In gradual steps, so sometimes there could be minor changes and maybe a filename that you referenced in one document Could be changed so the file has been renamed or Perhaps there was a small refactoring to some part of a function and Sometimes the whole picture is different. The entire logic has been changed People added something removed something made a very big change to the actual implementation To make sure the documentation is always up to date We need to do it Continuously for example on every pull request in this way developers can know that the documentation They read is indeed up to date and then Documentation is something you can trust you can read a document and know that it is true It is accurate and it explains and describes the state of the code as it is right now To make sure the documentation is always up to date what we need to do is to check the documentation and the code And if the code changed we're going in need to update the documentation accordingly to reflect the code's new state Without code couple documentation. This would be impractical and almost impossible It would mean you have to read all of your documents which consists of basic text Understand what's happening there and then look at the code and look for inconsistencies or changes Thanks to code couple documentation this task becomes easier. It means that what we need to do For every document is look at the code parts that it references and see if they changed Of course tools that do this automatically can ease up the process a lot We should do this continuously just like continuous testing when we know that the tests pass for example after every commit or before Merging a pull request just the same we can do with documentation Make sure the documentation is up to date before every pull request is merged for example by Embedding relevant tools into your continuous integration system that way or another by making sure the documentation is always up to date We make sure documentation is relevant and the developers can trust it The third principle of continuous documentation calls for creating the documentation when best and By this we mean not when the ship has sailed but as part of the development workflow a Classic approach to creating documentation would include focusing the creation on concentrated sprints This usually happens when you understand that there are a bunch of new people coming to the team and there is going to be so much they need to understand and Isn't currently covered by the documentation that you want to write a lot of documents Or you just find out that currently current team members don't understand so many things and the documentation is lacking Or when you find out that a lot of it is already outdated and you need to read through it update it and create new documentation on the way The downside to this approach is that it makes creating documentation really hard Let's say you want to document some part of the code that you implemented, but you implemented it along why ago Let's say a few months ago. Now you want to document this part, but all the relevant information isn't fresh on your mind You're not sure why you did every little thing you did there You're not sure what implementation details are still crucial and to explain and what implementation details aren't so crucial to explain Maybe the code is even changed by other people and now you need to understand what they added to the code in addition to what you did originally But that's even the easy case on some cases We need to document some parts of the code, but the most relevant person for writing that documentation is no longer a part of the team that person has left or is currently unavailable and so we need to find someone who doesn't know the code well to Understand it completely from scratch and then document it Which would never be the same as the person who really understood the code while writing it in the first place The alternative would be creating documentation Continuously as part of the development workflow. For example, just after finishing implementing a very important feature or after fixing a crucial bug If you try to create documentation Just when the information is fresh on your mind, the process is much easier You remember the motivation to why you implemented the feature to all the decisions you took while deciding how to implement it And to all the small specific details that you need to describe Creating documentation continuously makes the process so much easier To do that you could follow different approaches You could decide that big pull requests or important pull requests include the documentation within them You can decide to dedicate some time after every sprint for creating documentation You can use tools that will help you and suggest where new code has been added that you might need to document it regardless of the approach you choose Creating documentation continuously rather than on concentrated sprints will make it much easier And by following this approach and creating documentation in gradual steps You will slowly increase the coverage of documentation of your code To recap we agree developers deserve and need Good high-quality documentation now we can be more specific developers and developers teams need and deserve Practical code coupled and always up-to-date documentation that they can trust Unfortunately current tools and practices are too hard and don't serve developers. So this is rarely a reality Therefore code documentation requires new methods and tools What iscribed continuous documentation? Which calls for creating and maintaining documentation in a way that incorporates it into the development workflow In other words we treat our documentation as we treat other crucial parts of the workflow for example tests or the code itself According to continuous documentation the documentation should be code coupled always up-to-date and Created when best I believe the way we share knowledge and code Has to change if I go back to my students from the story I shared with you in the beginning of this talk I would like to hear different stories from them and from other people joining their new jobs and starting to onboard your new code base I want to hear that it's an interesting and fun experience to Look around so many lines of code that people have written over time But with the documents that help you that guide you through the code that explains the big picture as well as the small Details they need to know in that case even if the relevant people who created that code are no longer Part of the team it shouldn't be so intimidating when such documentation exists It helps in so many ways it eases up onboarding It helps teams become more flexible as you can shift between tests in various parts of the code base It also helps you when you have this bug right now affecting production. I Believe we can start implementing the principles I shared here with you on small steps We can start in our teams and gradually improve them over time I hope that the principles and the concepts I shared here today would encourage you to rethink the way you share knowledge on code in your teams And the way we as developers in general share knowledge on code. I Would love to hear your thoughts about it. I'm curious What do you think about continuous documentation or documentation in general? So please feel free to reach out to me after this session. Thank you so much for joining and happy documenting