The Power of Documentation: How to Code Smarter, Faster

Welcome to Building Better Developers, the Developer Noir podcast, where we work on getting better step by step professionally and personally. Let's get started. Well, hello and welcome back. We are in a season of Developer Noir, Building Better Developers with AI. Yes, this time we're going through a couple of seasons back. We're actually taking the same topics, essentially the title from those episodes. We're throwing it into AI, chat GPT specifically, and we're going to see where it takes us. So far, it's been pretty darn good. So we're going to see again what happens today. First, let me introduce myself. My name is Rob Brodhead. I am one of the founders of Developer Noir, also the founder of RB Consulting, where we help you work your way through your technology junk drawer, basically. We sit down with you, talk about your business, where you want to go, and then we use our experience in a lot of different lines of business, different areas to figure out what is the best solution for you. How do we craft a technology roadmap for your business? And how do we take what you have and find ways to do it better through simplification, integration, automation, innovation? We find ways to take what you do and do it better, do it faster so that now you can work on your customers and making them happy instead of working in your business all the time. Good thing, bad thing. Let's see. Good thing is I've got a son that is moving off to South Carolina, and we just took a weekend with them to check the area out. And it was amazing how many places, like every time we went somewhere, it was somewhere cool. We found the first night we were there, we'd driven all day. We said, we just want to go hang out somewhere. We found a place that had darts, pool, shuffleboard, some video games, the virtual golf. It was an Irish pub that was basically called like the Irish pub or something like that. So you sort of, you know, you get a pretty good picture of what it is. Great time. Bad thing would be through all of this, one of the days happens to be the one day out of a month that they do like their downtown is just like festival day. And it was also, I think, four hundred and seventy eight degrees out something like pretty close, you know, plus or minus one or two degrees. So it was really hot. We were just trying to grab something to eat and it was just full of vendors that were not food. We ended up walking literally, it was almost a mile. It was a really long road, lots and lots of stuff. We finally found somewhere, but that was miserable. That was one of the things the heat alone, I think, took it out of us for like the rest of the day and maybe half of the next one. Hopefully I have not taken too much out of Michael and he still has the energy to introduce himself. Go for it, sir. Hey, everyone. My name is Mike Melosh. I'm one of the co-founders of developer building better developers. I'm also the owner and founder of Envision QA, where we help startups and growing companies improve their software quality through a series like test planning, automation and release support. Why do companies work with us? Because buggy software costs time, money and customer trust. We make sure products are reliable before launch, helping teams move faster and avoid costly mistakes. If you're building something great and wants to run smoothly from day one, visit EnvisionQA.com or shoot us an email and let us know what you need. Let's see, good things and bad things. Good things. Projects are going well, making headway on a lot of things, kind of get over some blockers. So, the bad thing, running a little behind on some of these projects and because of those blockers. So, it was kind of a two-sided coin. The bad thing essentially led to the good thing. Hopefully we'll continue that progress. So, talking about good things is we have AI helping us out this time. So, this episode we're going to go with the title was the power of documentation, transforming your development practices. This one just like comes right into it. It doesn't give me anything like, hey, that's a great idea or anything like that. It just comes in. Episode objective, help developers and technical leaders understand why documentation matters, where it adds the most value and how to build a documentation culture that scales with software and teams. So, let's get right into the key talking points. I think this goes back, oh no, it's not 10 points again. So, let's see where we go. First one, why developers hate and need documentation. Bullet point one, common reasons developers avoid it, perceived low ROI, time consuming, real world consequences, second bullet, real world consequences of poor or missing docs, onboarding issues, tech debt, misunderstood code bases. So, start right there, why developers hate and need documentation. I think I want to address the first one, common reasons developers avoid it, perceived low ROI, and time consuming. Now, it's sort of funny that when we are doing episodes on AI, I'm going to start right out of the bat and say, you can use AI to help document your code and save a lot of time in that. Now, there are some approaches and this gets into the perceived low ROI. You're like, well, okay, fine, I'm writing some comments. How's that going to help? Well, six months from now, you was going to say that helps a lot because otherwise I would have had no idea what this code's doing, particularly if you've got magic numbers or you've got very complex logic or you've got something in there that is to specifically address a bug that's maybe a data issue or something that could easily be not apparent to somebody looking at the code. That could be you or it could be somebody else. Now, that will save you potentially a lot of time. I will argue though, much like, and we talked about test driven development, there is, we'll call it comment driven development or something on comment driven design maybe is where instead of just diving into your code and just writing your boom, I'm flinging code actually walk through just like you were probably taught in college or wherever you went to school pseudo code right through, write some comments down to say, okay, I'm going to do this. I'm going to do this. I'm going to do this. I'm going to do this. Funny enough, if you have AI generate code for you, a lot of times that is what it's going to do as well is it's going to take essentially whatever you ask it to do and it's going to turn it into some like comment bullet points of some sort and then put code around it. The nice thing about this and why the ROI is actually very high on this is I think at least for myself and I have a feeling that others of you are like this when we slow ourselves down and actually walk through the process that we were about to code, there is some design that goes on to it because we're thinking about the solution, but now we haven't already we're not being distracted by the code itself. We're thinking about like what are the actual tasks we need. This is very important regardless of what you're doing. If you're solving a problem, one of the things when you get to the solution is you need to say, okay, what are the steps to solve the problem? And then how do I execute on each step? And so I think when you do things like that, one, it actually saves you time because now it's not just self documenting code from a comments point of view, but also you could take that, lift it out and turn it into design docs or pull it from design docs and use that as essentially your starting point, saving you a lot of time to generate it in the first place and then also giving you even higher ROI because now you have some ways potentially to very directly tie your code back to heaven forbid a requirement or something like that. I'm going to stop there because I know there's a lot of ways we can go and I'm going to toss this over you and see, sit back and see where you want to go with it. So I'm going to, I liked how you started out the discussion on this. I want to kind of segue it just a little bit. So when we talked about like commenting and documenting our code, writing good comments is really good, but also essentially writing code that documents itself. So the naming of your variables, the naming of your methods, if you essentially all of it, almost try to code with real, real language in your code, just reading the code is like reading a paragraph, reading requirements. You don't have to spend the extra time writing additional comments because the code essentially self-documents itself. So I wanted to touch on that first because you kind of alluded to that, but didn't quite touch on that directly. Secondly, I liked the idea of starting out by putting the documents or requirements in the code. But a lot of times, even in college or when we teach presentations in some of our classes, pseudo code is one of the best ways to start commenting and documenting your code. You take your requirements, you kind of put bullet points. Hey, this is kind of what I wanted to do. And then you start filling in the gaps. Or if you're teaching, you kind of say, okay, here's what I want the program to do. So you kind of put like one, two, three, four, five, six, and then you start putting in what the steps are. And then underneath that, you start pseudo coding or you start kind of filling in the gaps of what it needs to be. And then at the end of it, one or two things can happen. One, if you're doing test-driven development, you've just written your test to then flip over to your code. So you have a test to essentially test your code. So you have the requirement to test there. Secondly, code with documents in mind. I like how you talked about that with the requirements. So with the pseudo code idea, the teaching idea, one thing before I ever write code is I look at the requirements. I try to understand the requirements. And now in today's world of AI, you can kind of write out your thoughts on those requirements into a chatbot and say, okay, here is what I'm thinking about doing here. The requirements for this application I want. Give me some pseudo code. Give me some code or better yet, and I found this to be extremely helpful, explain to me what these requirements are trying to do. And if I've covered all the bases for what the why is, what is it that I'm trying to solve? And what's interesting is not always, but every now and then you're going to get some very good feedback, very good documentation that you could almost literally take that documentation and drop it into a file and then start filling in the blanks, start writing your code to the documentation. Sometimes it could even find those edge cases that you missed that are going to bite you later. So this is just one of those ways where documenting early or using documentation to write code can help you write better code. I think those are all, I think all goes back to that ROI. I think that there is definitely a lot of value in doing it. And it does. It's just to sort of not to beat a dead horse, but as Michael suggested, it's like, it really is like when you were taught to write essays, you started with an outline and then like, you know, what are your key points and then the bullet points. And then you would flesh that out and turn it into your essay. It's the same thing that we're doing with code effectively. Now moving on, documentation is a development superpower. Three bullets here. How good docs reduce bugs, improve velocity and make maintenance easier. Second one, documentation is a force multiplier onboarding API's DevOps testing. And third one, the hidden cost of not documenting. Now I'm going to go with, because this is one that has been near and dear to my heart for a while, is API's, particularly because the API documentation tools that are out there are to me invaluable as part of developing API's. When you're using Swagger or things like that, or tools like Postman, which is an awesome way to generate code in a lot of different languages to call whatever your API endpoint is. These things allow you to go through and very quickly flesh out essentially, you know, some key things. Now API's of course, they are, you know, you've got your endpoints, which is always the starting point there. Like here's all the things we need to do. Here's all the accesses or how we need to do them. And then from there though, again, it's very much an outline and a fleshing it out. So what does it take? What is the signature? What is the inputs? What are the outputs? What are some of the exceptions? What are the errors? What does a successful execution of this look like? What does it return? Things like that are a lot of times they're going to be part of what your code generator or what your tool is going to use. But it's also some stuff that now it's starting to blur the line a little bit because you can use these same generators that say, okay, here's my WSDL and go generate a client. And now suddenly you've got a client and it's got documentation around it because it's the most basic stuff. It's what are the signatures? What are the outputs and things like that? But it's a starting point. And then to me, it almost begs you to just add a paragraph or a sentence here and there to just say, this is what this value is. This is what this variable is. This is what I'm expecting. And it's one of those things it's like here, this is almost all you need. Please spend an extra couple of minutes and make it look awesome. So the tools are out there and it really is a force multiplier, especially when you start using like swagger and things like that, where they're also generate, they use that to generate test suites, basically a test bed. So you can go in and you can say, okay, I just wrote all this stuff. Let me go in and without having to write a bunch of client code or anything like that, I can go right into the documentation and it has the things it needs to go actually test the code I wrote. Heaven forbid we use the T word, but I do see it as that. I think this is something that it comes back to what we said before. You're going to design better. You're more tightly required, tied to requirements. You're thinking about your why and then you're actually implementing stuff and able to test it. So again, lots of places we can go. So where do you want to go on this one? So I think I want to do that last one again. Can you read it to me? The hidden cost of not docu. Yes. So there's actually two things with that. So there's a hidden cost to not document, but there's also a hidden cost to not maintaining your documentation. So I've been in situations where organizations don't document and then you have people leave and then you have people come in and people can't maintain the existing software. It gets ugly. A lot of times, sometimes it depends on the state of the company or the project that you're on, where sometimes you're very quick to fail. You're trying to get there as fast as you can get prototypes out there. You just don't take the time to document. That's fine. Sure. I get it. However, you should be applying some type of documentation to your code, either through well written code. Basically the code documents itself. Some type of code level comments, Java docs, or some type of comments within the code where you could essentially generate documentation from the code. However, a lot of organizations use things like Confluence or Microsoft project. They use external tools to document and record all the requirements, but they never get updated through the process of the project. So as the life of the project expands, the code, the tickets, all that changes, the documentation gets stale. So if you are going to do documentation, do it as close to the code level as possible and use tools to extract that documentation from the code to something more manageable and readable for the business. It could be read-bees. It could be markdown languages. It could be one of the guys I work with now actually has a tool that reads the markdown from the project and generates Confluence pages and updates them every time they do a release. It goes and flushes and updates all the documentation in Atlassian. So there are multiple ways to do this. It just takes the time, a little bit of planning, and honestly, if you're a coder, you should be writing self-documenting code or at a minimum, put something in the code to tell you what the method is doing. Naming is important. A pro tip for this is that something I ran across a company that did this and I really do like it is that when they do tickets, part of the ticket, there is a sub ticket basically that is testing and one that is documentation. And you can't actually close your ticket out until you close out the testing and the documentation. Now, the funny thing is, is there were a lot of tickets that would stay open a long time because people weren't getting their documentation or their test written out. However, it does work out to be something that gives you that reminder that's like, oh, yeah, I do need to clean this thing up. So that's a little pro tip. We'll do a, we'll jump in real quick on this one. Maybe. Well, there are three types of documentation that matter. Code comments versus system level docs. Readme files, your project's first impression. Architecture diagrams and decision records. Setup guides, API docs, test strategies, how to deploy checklists, run books for ops and incident recovery. I want to just like touch on this one real quick so we don't go too long because we easily could. Your readme, I think, is a very important part of any project is to have wherever it's whether it's in your GitHub repository or your repository happen. It is somewhere there should be at the root a readme. A lot of times it's a markdown, especially if you use GitHub by default. And it should walk through. This is what it is. This is how you get started. This is where the code is. This is how you build it. Things like that. Those things all need to be a part of that because otherwise, trust me, it is a real pain to get code and you somebody's like, oh, just pull the code from here. And now you really don't. Yeah. I mean, you sort of know if you know it's a Python app, maybe you can guess your way through it or if it's React or if it's Node or Java. There's various things that you can do to like figure it out. But why figure it out when you could just have it written out? Thoughts? So the last one you mentioned, the run books, that's another one that's very critical and important because if you don't know how your software gets deployed or what services it's deployed on, you're in trouble. If it goes down, how are you going to bring it back up? How are you going to release new software? And if someone leaves, you don't want that critical information going out the door with the person that leaves. You want to know how to maintain and support your software. So at a minimum, make sure it's either in a read me some type of script, but you have something written somewhere that tells you how to take your software from development to production. And now we're going to take you from the beginning of the podcast episode to the end of the podcast episode. We are wrapping this one up. I want to thank you so much. We do appreciate you hanging out with us for this while. You can show us your appreciation by shooting us an email at info at developer.com. We would love to hear your feedback. Plus any suggestions you have for future episodes and things of that nature. If you've got somebody that you would like us to talk to from an interview point of view, we're trying to get some of those still worked out. We're happy to. There's a lot of people out there that we would have no problem talking to. Obviously they may have problems talking to us because, well, you know us now. That being said, check us out wherever you check out podcasts. If you find somewhere with podcasts, you can't find us. Let us know. We'll add it in there. Check us out on the developer channel on YouTube. There's a lot of stuff out there. Also the developer website. There is a lot of stuff there and we are looking into as we have for a while, but we are back again, spending a little bit of time looking at the development. We're back again spending a little bit of time looking at maybe some ways that we may adjust some of our material, our content, some things like that. A lot of it is just to make it easier for you. So if you have a any preferences or any input on how you would like to see this thing, this model, this huge repository of content that we have presented, love to hear it from you. That being said, gone too long. So I'm just going to wrap it up until you have a great day, a great week, and we will talk to you free of charge then. Thank you forires. This was an analysis ... Thank you for listening to building better developers to develop a new podcast. You can subscribe on Apple podcasts, Stitcher, that Amazon, anywhere that you can find podcasts. We are there. And remember just a little bit of effort every day ends up adding into great momentum and great success. you