Detailed Notes
In this episode of Building Better Developers with AI, Rob Broadhead and Michael Meloche revisit one of the most overlooked tools in a developer’s toolbox: the power of documentation.
Using ChatGPT, they revisit a previous episode and extract fresh insights to explore how documentation impacts onboarding, testing, deployment, and team velocity. No, we’re not using AI to write the docs, but to guide the conversation and make it more valuable.
🎯 Episode Highlights: - Why developers avoid documentation—and why they shouldn't - Comment-driven development and self-documenting code - API documentation tools like Swagger and Postman - How stale documentation hurts your team - The #DevDocChallenge for better habits
🛠️ Tools Mentioned: - Swagger: https://swagger.io/ - Postman: https://www.postman.com/ - MkDocs: https://www.mkdocs.org/ - JSDoc: https://jsdoc.app/
📢 Developer Challenge: Pick one part of your project—README, runbook, or method comments—and improve its documentation this week. Tag your progress with #DevDocChallenge.
đź“Ś Listen to the full podcast and more episodes: https://develpreneur.com/power-of-documentation/
#Documentation #SoftwareDevelopment #ChatGPT #DeveloperPodcast #BuildingBetterDevelopers #DevDocChallenge
00:00 - Pre-show 00:47 - Revisiting Topics with AI: A Season of Reflection 01:05 - Meet the Hosts 04:38 - What AI Suggested About Documentation 05:14 - Why Developers Avoid Documentation 06:00 - AI for Speeding Up Code Comments and Docs 07:20 - Comment-Driven Development and Pseudocode Planning 08:36 - Self-Documenting Code and Good Naming Practices 10:36 - Writing Code from Requirements with AI Support 12:11 - Documentation as a Superpower in Dev Teams 12:48 - API Docs: Swagger, Postman, and Dev Velocity 14:43 - Tying Docs to Testing and Better Requirements 15:25 - The Hidden Cost of Not Documenting 16:58 - Keeping Documentation Close to the Codebase 18:12 - Enforcing Documentation via Development Tickets 18:50 - What to Document: README, Architecture, and Runbooks 20:02 - Why Runbooks Matter for Deployment and Support 20:30 - Thanks and Podcast wrap-up 21:54 - Bonus: Building a Documentation Culture 22:18 - Tools for Docs as Code: MkDocs, Notion, Confluence 23:06 - Markdown, ASCII Docs, and Daily Note-Taking 24:07 - One Final Tip: Save Your Notes and Tabs! 26:12 - Closing Thoughts and Thank You!
Transcript Text
[Music] Boom. We're going to dive right in again. This one uh we're going to do the power of documentation transforming your development practices and we're going to see what AI has to say about that. Wonder if I can do this. Try to like get this so it's a little easier for me to read. >> Then I'm too short. So get my height right and all that kind of good stuff. See these are the challenges of videos over podcast. I never worried about what I look like in the podcast. As you can tell, I don't really worry about that now either. >> Okay, you moved your audio dropped a little. >> Audio dropped. Is that better? >> Uh, one more time. >> Let's try that. Is that better? >> Yeah, that's much better. >> Is that still good? >> Yeah. >> Okay, let's try that. We'll see how that works. And we're going to do our little three, two, one. Well, hello and welcome back. We are continuing share our season of developer, building better developers with AI. Yes, this time we're going through a couple 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. And 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 Broadhead. I am one of the founders of Developer, also the founder of RB Consulting, where we help you work your way through your technology trash draw, 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, uh, different areas to figure out what is the best solution to 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? Uh, let's see. Good thing is, uh, I've got a son that is, um, moving off to South Carolina and we just took a a weekend with them to like check the area out. And it was amazing how many places like every time we went somewhere, it was somewhere cool. We had like we found the first night we were there, we'd like driven all day. We said, "Let's we just want to go like hang out somewhere." We found a place that had darts, pool, shuffle board, some video games, uh the virtual golf. It was uh and it was a an Irish it was a Irish pub that was basically called like the Irish pub or something like that. So, you sort of, you know, you you get a pretty good picture of what it is. Great time. Uh bad thing would be uh 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 478 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 those 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 Michael Malash. I'm one of the co-founders of Developer Nerve, 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 want 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. Uh good things, uh projects are going well, making headway on a lot of things. Kind of got over some blockers. Uh bad thing running a little behind on some of these projects and because of those blockers. So, it was kind of a a two-sided coin. Um the bad thing essentially led to the good thing. Uh 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. And this one just like comes right into it. Doesn't go, you know, didn'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 for common reasons developers avoid it. Perceive 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 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 low ROI. You're like, well, okay, fine. I'm writing some comments. How's that going to help? Well, 6 months from now, you is 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've talked about test driven development there is we'll call it uh comment driven development or something like comment driven design maybe is where instead of just diving into your code and just writing your you know 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 are about to code there is uh some design that goes onto it because we're thinking about the solution but now we haven't already we're not being uh 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 to you and see sit back and see where you want to go with it. >> So I'm going to I like how you started out the discussion on this. I want to kind of segue it just a little bit. So when we talk about like commenting and documenting our code um 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 almost try to code with real uh real language in your code, just reading the code is like reading a paragraph, reading requirements. it's 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 uh touch on that directly. Uh secondly, um I like the idea of starting out by putting the docu 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 you kind of say, okay, here's what I want the program to do. So, you kind of put like 1 2 3 4 5 6 and then you start putting in, you know, 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 test there. Uh secondly, uh code with documents in mind. I I liked 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 are 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 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, then drop it into a file and then start filling in the blanks, start writing your code to the documentation. Uh 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 that all goes back to that ROI. think that there is definitely uh a lot of value in doing it and it does it's as you know just to sort of not to beat a dead horse but as Michael suggests 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 APIs, DevOps testing. And third one, the hidden cost of not documenting. Now, I'm gonna go with uh because this is one that has been near and dear to my heart for a while. um is APIs particularly because the API documentation tools that are out there are to me invaluable as part of developing APIs 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. Um these things allow you to go through and very quickly flesh out essentially you know some key things. Now APIs of course they are you know you've got your end points which is always the starting point there of like here's all the things we need to do here's all of 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 is this 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 uh execution of this look like? What does it return? Things like that are a lot of times are going to be part of what your code generator or what your your tool is going to use. Uh, but it's also some stuff that now it's it's starting to blur the line a little bit because you can use these same generators that say, "Okay, here's a, you know, like 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 it's to me it almost like it almost begs you to just add a paragraph or not even a paragraph 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 like 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 uh it comes back to what we said before. You're going to design better. You're more tightly require 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 uh I think I want to do that last one again. Can you read it to me? Uh uh >> the hidden cost of not document. >> Yes. So there's actually two things with that. So there's a hidden cost to not document, but there's also a hidden co 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 it gets ugly a lot of times. Um, sometimes it depends on the state of the company or the project that you're on where sometimes pe you're very like 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 uh code level comments um Java docs or you know 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 uh you know pro 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 uh 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 reads. It could be markdown languages. It could be uh one of the guys I work with uh now actually has a tool that reads the markdown from the project and generates confluence pages and updates them every time uh they do a release. It goes and flushes and updates all the documentation in uh Atlassian. So you 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. U a pro tip uh for this is it's something I ran across a company that did this and I I really do like it is that when they do tickets part of the ticket there is a a subt 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 tests written out. However, it does work out to be something that gives you that reminder. It's like, "Oh, yeah. I do need to clean this thing up." So, uh, that's a little pro tip. We'll do a we'll go we'll jump in real quick on this one. Um, maybe, uh, we'll three types of documentation that matter. code comments versus system level docs, readme files, your first your project's first impression, architecture diagrams and decision records, uh setup guides, API docs, test strategies, how to deploy checklists, runbooks for ops, and incident recovery. I want to just like touch on this one real quick um so we don't go too long because we easily could. uh your your readme I think is a very important part of any project is to have wherever it's whether it's in your uh 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, "Well, 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 if it's a Python app, maybe you can guess your way through it or if it's React or if it's Node or you 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 runbooks. 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 readme, 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 [email protected]. We would love to hear your feedback. plus any suggestions you have for future episodes and things of that nature. Uh 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. Uh we're happy to. There's a lot of people out there that we would have no problem talking to. Uh 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. Uh if you find somewhere with podcast 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 development of our 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 way maybe some ways that we may uh 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 uh any preferences or any input on how you would like to see this thing, this mon this huge like repository of content that we have presented. Love to hear it from you. That being said, I've 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 next time. Bonus material. Uh actually, let me do uh there was a point a four and a five. So we'll go through these real quick. Transforming your team through documentation. Encouraging a writing culture and dev teams. Assigning doc responsibilities, not always the junior dev. Tools like make docs, sphinx, notion, github, wikis or confluence. The docs's code approach keeping documentation version controlled. Documenting for future you. Personal developer notes and knowledge capture. Uh zetto casten obsidian for example. uh creating searchable trails of thought for complex solution. So there's a Wow, that is definitely the bonus uh materials. So I'll let you start like where do you where do you want to go with those? >> I was actually going to go with the ASI docs which I've talked about before. We've done a tutorial on that and I have lost the source code for that. Uh so apologies. I'll do an updated version uh soon because it has updated. But given that most of the code repositories use markdown as kind of their base documentation uh tool, ASI docs is probably one of the easiest lang markdown languages to learn. But you can actually literally take your notes in markdown have the viewer right there and it just translates it to a web viewer. You can go and make modifications. But it is just one of those kind of cool little tools to use. you get used to writing in markdown. Uh I know you like me, we tend to spend more time in Notepad, Notepad++, some type of just editor and that's where we just live. We put notes, we copy and paste code in there and we live there. But if you can write in Markdown, a lot of those tools have viewers. So you can literally write your documentation as you're just doing your daily notes. So if you find yourself doing that, look at using some tools like that. And even um on top of that you can do things like Microsoft note, OneNote um some like Google note. A lot of those also have uh markdown plugins that you can plug into it. So again use any type of tool but just start learning uh a variation of note takingaking that can be converted to documentation be it in code or in notepad. I think the key there and that's the bonus is whatever it just something that works for you whether it is whether you you get comfortable with markdown a lot of people use that it's very common uh if you want to like there's so many wiki tools out there confluence is a a very big one at lassian set of tools doing something like that that is where you can take notes uh a lot of tools like I'll I will save you know I will have usually a text file open somewhere in my repository whatever code I'm working on that maybe I'm writing stuff. I have SQL scripts open all the time that are I save them out as I'm like running little queries and things like that so I can go find how did I do that weird query before. Um those kinds of things are excellent and any of these tools like notion and some of those things that are out there that are becoming better about just trying to capture ideas. Um it just comes down to whatever the tool is just find and feel free to you know obviously you can play around and just find the thing that works best for you and that is the one that you need to use. One last tip. We've talked about all this documentation. We've talked about all these tools. Make sure you go through your tools at the end of the week and if you have 50 tabs open in notes, Notepad, whatever, save those off. Back them up because Notepad and that will they save locally, you can still lose them. And nine out of 10en times that's something you probably need to keep around forever. So, I only mention this because this bit me recently. I accidentally closed a tab that I shouldn't have closed and I lost my note. Uh, but the whole part about documentation is make sure that you do store it, you do save it, you do keep it around somewhere where it can be easily accessible. Yes, 100%. Yes, make sure that you click the save button. I have had a few of those myself where I forgot to do that and then I ended up, you know, smacking myself in the head for it. As always, not only we appreciate you even more than those that listen to the podcast only because you have to actually see us, but you know, and I know that detracts from the the whole content, but any way that you want to reach out to us, uh, feedback on the podcast or actually here, leave us comments, leave us notes. I assume there's ways to like it and stuff like that. I'm not I'm not super up on YouTube itself, but anyway, share it out. Let your friends know. Let us know more importantly what you think and where we can help you out because that's really what we're here for is to help you get better. As always, thank you so much for your time. We will be back doing more with AI. AI. AI. Okay, that doesn't work very well. And I'll try to get better special effects next time around. Have a good one everybody. Talk to you next time. [Music]
Transcript Segments
[Music]
Boom.
We're going to dive right in again. This
one uh we're going to do the power of
documentation transforming your
development practices and we're going to
see what AI has to say about that.
Wonder if I can do this. Try to like get
this so it's a little easier for me to
read.
>> Then I'm too short. So
get my height right and all that kind of
good stuff. See these are the challenges
of videos over podcast. I never worried
about what I look like in the podcast.
As you can tell, I don't really worry
about that now either.
>> Okay, you moved your audio dropped a
little.
>> Audio dropped. Is that better?
>> Uh, one more time.
>> Let's try that. Is that better?
>> Yeah, that's much better.
>> Is that still good?
>> Yeah.
>> Okay, let's try that. We'll see how that
works.
And we're going to do our little three,
two, one. Well, hello and welcome back.
We are continuing share our season of
developer, building better developers
with AI. Yes, this time we're going
through a couple 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. And 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
Broadhead. I am one of the founders of
Developer, also the founder of RB
Consulting, where we help you work your
way through your technology trash draw,
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, uh, different areas to
figure out what is the best solution to
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? Uh, let's see.
Good thing is, uh, I've got a son that
is, um, moving off to South Carolina and
we just took a a weekend with them to
like check the area out. And it was
amazing how many places like every time
we went somewhere, it was somewhere
cool. We had like we found the first
night we were there, we'd like driven
all day. We said, "Let's we just want to
go like hang out somewhere." We found a
place that had darts, pool, shuffle
board, some video games, uh the virtual
golf. It was uh and it was a an Irish it
was a Irish pub that was basically
called like the Irish pub or something
like that. So, you sort of, you know,
you you get a pretty good picture of
what it is. Great time.
Uh bad thing would be uh 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 478 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 those 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 Michael
Malash. I'm one of the co-founders of
Developer Nerve, 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 want 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. Uh good things, uh
projects are going well, making headway
on a lot of things. Kind of got over
some blockers. Uh bad thing running a
little behind on some of these projects
and because of those blockers. So, it
was kind of a a two-sided coin. Um the
bad thing essentially led to the good
thing. Uh 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.
And this one just like comes right into
it. Doesn't go, you know, didn'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 for common reasons
developers avoid it. Perceive 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 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 low ROI. You're like,
well, okay, fine. I'm writing some
comments. How's that going to help?
Well, 6 months from now, you is 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've talked about
test driven development
there is we'll call it uh comment driven
development or something like comment
driven design maybe is where
instead of just diving into your code
and just writing your you know 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 are about to
code
there is uh some design that goes onto
it because we're thinking about the
solution but now we haven't already
we're not being
uh 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 to you and see sit back and
see where you want to go with it.
>> So I'm going to I like how you started
out the discussion on this. I want to
kind of segue it just a little bit. So
when we talk about like commenting and
documenting our code um 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
almost try to code with real
uh real language in your code, just
reading the code is like reading a
paragraph, reading requirements. it's
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 uh touch on that directly.
Uh secondly, um I like the idea of
starting out by putting the docu
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
you kind of say, okay, here's what I
want the program to do. So, you kind of
put like 1 2 3 4 5 6 and then you start
putting in, you know, 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 test there. Uh secondly,
uh code with documents in mind. I I
liked 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 are 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 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, then drop it into a file
and then start filling in the blanks,
start writing your code to the
documentation. Uh 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 that all goes back
to that ROI. think that there is
definitely uh a lot of value in doing it
and it does it's as you know just to
sort of not to beat a dead horse but as
Michael suggests 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 APIs, DevOps
testing. And third one, the hidden cost
of not documenting. Now, I'm gonna go
with uh because this is one that has
been near and dear to my heart for a
while. um is APIs particularly because
the API documentation tools that are out
there are to me invaluable as part of
developing APIs
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. Um these things
allow you to go through and very quickly
flesh out essentially you know some key
things. Now APIs of course they are you
know you've got your end points which is
always the starting point there of like
here's all the things we need to do
here's all of 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 is this
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 uh execution of this
look like? What does it return? Things
like that are
a lot of times are going to be part of
what your code generator or what your
your tool is going to use. Uh, but it's
also some stuff that now it's it's
starting to blur the line a little bit
because you can use these same
generators that say, "Okay, here's a,
you know, like 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 it's to me it almost like
it almost begs you to just add a
paragraph or not even a paragraph 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 like 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 uh it comes back
to what we said before. You're going to
design better. You're more tightly
require 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 uh I think I want to do that last one
again. Can you read it to me? Uh uh
>> the hidden cost of not document.
>> Yes. So
there's actually two things with that.
So there's a hidden cost to not
document, but there's also a hidden co
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 it gets ugly
a lot of times. Um, sometimes it depends
on the state of the company or the
project that you're on where sometimes
pe you're very like 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 uh
code level comments um Java docs or you
know 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 uh you know
pro 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 uh 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 reads. It could be
markdown languages. It could be uh one
of the guys I work with uh now actually
has a tool that reads the markdown from
the project and generates confluence
pages and updates them every time uh
they do a release. It goes and flushes
and updates all the documentation in uh
Atlassian. So you 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.
U a pro tip uh for this is it's
something I ran across a company that
did this and I I really do like it is
that when they do tickets part of the
ticket there is a a subt 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 tests written
out. However, it does work out to be
something that gives you that reminder.
It's like, "Oh, yeah. I do need to clean
this thing up." So, uh, that's a little
pro tip. We'll do a we'll go we'll jump
in real quick on this one. Um, maybe,
uh, we'll three types of documentation
that matter. code comments versus system
level docs, readme files, your first
your project's first impression,
architecture diagrams and decision
records, uh setup guides, API docs, test
strategies, how to deploy checklists,
runbooks for ops, and incident recovery.
I want to just like touch on this one
real quick um so we don't go too long
because we easily could. uh your your
readme I think is a very important part
of any project is to have wherever it's
whether it's in your uh 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, "Well,
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 if it's a
Python app, maybe you can guess your way
through it or if it's React or if it's
Node or you 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
runbooks. 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
readme, 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
[email protected]. We would love to
hear your feedback. plus any suggestions
you have for future episodes and things
of that nature. Uh 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. Uh we're happy to. There's a
lot of people out there that we would
have no problem talking to. Uh 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. Uh if you find
somewhere with podcast 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 development of our
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 way maybe
some ways that we may uh 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 uh
any preferences or any input on how you
would like to see this thing, this mon
this huge like repository of content
that we have presented. Love to hear it
from you. That being said, I've 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 next time.
Bonus material. Uh actually, let me do
uh there was a point a four and a five.
So we'll go through these real quick.
Transforming your team through
documentation. Encouraging a writing
culture and dev teams. Assigning doc
responsibilities, not always the junior
dev. Tools like make docs, sphinx,
notion, github, wikis or confluence. The
docs's code approach keeping
documentation version controlled.
Documenting for future you. Personal
developer notes and knowledge capture.
Uh zetto casten obsidian for example. uh
creating searchable trails of thought
for complex solution.
So there's a Wow, that is definitely the
bonus uh materials. So I'll let you
start like where do you where do you
want to go with those?
>> I was actually going to go with the ASI
docs which I've talked about before.
We've done a tutorial on that and I have
lost the source code for that. Uh so
apologies. I'll do an updated version uh
soon because it has updated. But given
that most of the code repositories use
markdown as kind of their base
documentation uh tool, ASI docs is
probably one of the easiest
lang markdown languages to learn. But
you can actually literally take your
notes in markdown have the viewer right
there and it just translates it to a web
viewer. You can go and make
modifications. But it is just one of
those kind of cool little tools to use.
you get used to writing in markdown. Uh
I know you like me, we tend to spend
more time in Notepad, Notepad++,
some type of just editor
and that's where we just live. We put
notes, we copy and paste code in there
and we live there. But if you can write
in Markdown, a lot of those tools have
viewers. So you can literally write your
documentation as you're just doing your
daily notes. So if you find yourself
doing that, look at using some tools
like that. And even um on top of that
you can do things like Microsoft note,
OneNote um some like Google note. A lot
of those also have uh markdown plugins
that you can plug into it. So again use
any type of tool but just start learning
uh a variation of note takingaking that
can be converted to documentation be it
in code or in notepad. I think the key
there and that's the bonus is whatever
it just something that works for you
whether it is whether you you get
comfortable with markdown a lot of
people use that it's very common uh if
you want to like there's so many wiki
tools out there confluence is a a very
big one at lassian set of tools
doing something like that that is where
you can take notes uh a lot of tools
like I'll I will save you know I will
have usually a text file open somewhere
in my repository whatever code I'm
working on that maybe I'm writing stuff.
I have SQL scripts open all the time
that are I save them out as I'm like
running little queries and things like
that so I can go find how did I do that
weird query before. Um those kinds of
things are excellent and any of these
tools like notion and some of those
things that are out there that are
becoming better about just trying to
capture ideas. Um it just comes down to
whatever the tool is just find and feel
free to you know obviously you can play
around and just find the thing that
works best for you and that is the one
that you need to use. One last tip.
We've talked about all this
documentation. We've talked about all
these tools. Make sure you go through
your tools at the end of the week and if
you have 50 tabs open in notes, Notepad,
whatever, save those off.
Back them up because Notepad and that
will they save locally, you can still
lose them. And nine out of 10en times
that's something you probably need to
keep around forever. So,
I only mention this because this bit me
recently. I accidentally closed a tab
that I shouldn't have closed and I lost
my note. Uh, but the whole part about
documentation is make sure that you do
store it, you do save it, you do keep it
around somewhere where it can be easily
accessible.
Yes, 100%. Yes, make sure that you click
the save button. I have had a few of
those myself where I forgot to do that
and then I ended up, you know, smacking
myself in the head for it. As always,
not only we appreciate you even more
than those that listen to the podcast
only because you have to actually see
us, but you know, and I know that
detracts from the the whole content, but
any way that you want to reach out to
us, uh, feedback on the podcast or
actually here, leave us comments, leave
us notes. I assume there's ways to like
it and stuff like that. I'm not I'm not
super up on YouTube itself, but anyway,
share it out. Let your friends know. Let
us know more importantly what you think
and where we can help you out because
that's really what we're here for is to
help you get better. As always, thank
you so much for your time. We will be
back doing more with AI. AI. AI. Okay,
that doesn't work very well. And I'll
try to get better special effects next
time around. Have a good one everybody.
Talk to you next time.
[Music]