The Documentation Problem Every Dev Faces

Transcript is auto-generated and may contain errors.

Hey folks, we are going to a question from YouTube comments. It's from Epic Technav. Thanks again for sending in awesome questions. This one's around documentation. I don't have it directly in front of me obviously cuz I'm driving a vehicle, but a couple different angles on documentation. So, in their case, joining a new team, uh, of course things are like, you know, underdocumented. This is pretty standard, unfortunately. Um and then Epic Techna was asking for a couple different angles on this. So like you know how much is it expected that your code is self-documenting versus you have like written up documentation versus like architectural docs versus you know kind of what what's the mix on boarding like all this stuff like how do you balance that and then the other part their question was around um if I notice difference around this uh startups and big tech with respect to uh documentation so a bunch of different angles here uh I'm completely out of breath.

So, I apologize for sounding like an absolute pig just heaving into this microphone, but it's life right now from doing shuttle runs and burpees. Two of my most favorite activities. Um, okay. So, I I do have like a bit of a I don't know, like we all got our own opinions on things on this channel. You hear a lot of my opinion because it's my channel. Um, yeah, I have a probably a bit more of a bias against documentation and um, it's not because I don't think there's value in it. Um, it's because the the tax of maintaining certain types of documentation is very high. Oh, that's a lot of broken glass on the road, man. Um, we'll see if that's a problem for later. So, I think a lot of us, we see the benefit in having things documented, right? like there's a spot to go to and you can get information about the things that you have questions about.

And so like there's clearly there's clearly benefits to it. And I think that some of the drawbacks uh really to me they all kind of come back to like the tax to maintain and I think there are ways to minimize that tax. Uh, and sorry, by the way, when I'm saying tax, I just mean that like you have to you have to spend time and effort making sure they're up to date. Okay, so um there are ways to to minimize that tax. So, for example, with onboarding documentation, every time someone on boards and there are things that are out of date, they pay the tax for making it more effective for the next person, right? That way over time, if people know they're touching systems and things like that that are part of the onboarding Yeah. you know, try to make it a habit to go up to the onboarding documentation, but inevitably it's going to become a little bit behind because there's going to be misses and things like that.

So, the next person to go through pay some of that tax to make it better for the next person. And I think like honestly zero onboarding documentation is probably like way too chaotic, but you know, it's going to be out of date. So, um, if everyone plays a little bit of a part in keeping stuff up to date, I think that can help. I'm going to try to bring back, uh, some AI ideas into this conversation a little bit later if there's time and I don't forget, but that's onboarding, right? I think some of the questions uh, outside of onboarding, because this isn't the only time you want to read things, uh, like what about architecture? What about how things are designed in the code? Like how much of the code should be self-documenting or have comments in it? Right? This is going to be I think like wildly different depending on on uh different teams, different products, different services, how long things have been around.

Um like you're going to have so much variance here. I think there is like personally a lot of benefit to um highlevel architecture designs being captured. Okay. So when I think about architectural documents, we'll do like um we did a lot less of this in startups from my experience. Um, not saying that's the case for all of them, but in my experience, a lot less in Microsoft. Uh, and this will again vary from team to team. The team I'm on now is very heavy into like architectural documents and even in my organization, there is a like architectural review forum where design docs are brought in and people review them from different teams. So there's a pretty significant culture around it and I think there are a lot of benefits to going through design reviews, getting feedback from people. Like uh don't get me wrong, I think that when it comes time to implementing things, there's always going to be things that you didn't perfectly plan for.

Always. Let's get past this truck. Nice. Okay. Um, so there's always going to be stuff like that. And I mean, if your design, in my opinion, is good, then you can kind of, you know, not have to rip apart your whole design, do it from scratch. You make adjustments to the plan to accommodate. And so I think there's so much benefit upfront going into those conversations, having something common to to use as a like a forum to debate the ideas, record them, stuff like that. I think lots and lots of benefit. Um, one of the tricky parts is that like as your design becomes part of the code base, you now have it's kind of like when we think about code like when you have duplicate code and you have a bug in one spot or you need to add a feature to one spot but it's duplicated, you now have to maintain it in two spots.

And depending on how many times it's duplicated, you now have a tax to go maintain it in different spots, right? And there's risk to that because if you don't know all the spots, there's nothing enforcing that you touch it in all the spots. You get inconsistencies or broken behavior, blah blah blah. I think the same kind of thing can happen with architectural designs being documented in you know word documents, powerpoints, whatever else it happens to be VO documents you get drift from like what the system is in the code to what you have documented and again if you want to maintain that it's just a tax and I'm not saying the tax is never worth paying. I'm just saying that there is a tax. So if people aren't paying the tax or there's nothing to enforce it, now you have designs and architecture that are out of date with the codebase.

Now I am a firm believer that like everything we do is pros and cons and it's never I don't like saying never. Um it's rarely ever a situation of like you know all or nothing. It's a it's a spectrum. There's pros and cons, and we're on the spectrum trying to balance things. So, would I say that having architectural documentation that is 80% up to date and 20% behind, does that mean that that's automatically 0% value? No. I think there's still a lot of value in that, but you need to kind of go into it understanding that maybe you're taking it with a grain of salt. Like this is probably high level the direction of things, but understanding that there might be drift. So like my opinion is that I think it's very valuable to document architecture, but I would try to the stuff that you're trying to persist, right?

Having an architectural review document where people had their feedback and stuff recorded. Awesome. Don't lose that. It's a great record of like we made these decisions for these reasons. Okay. Um what I might do is take part of that and sort of have a highlevel architectural block diagram that's maybe easier to maintain, right? So that when people say, "Hey, I'm on boarding to this team. team. I want to understand how our product or service fits in or I'm building in this feature area of this product or service. How does that fit in? Then you have something easy visual to kind of refer to how these things connect. Okay. So, I think there's like sort of flavors of this that you can play with to get um the right balance of benefit versus tax to pay. And what I'm describing to you, like I'm not saying this is the right way or the only way.

I'm just giving you some ideas for like how you may want to approach balancing that. Maybe to you it makes sense to have like, hey, you wrote the architectural document. Always keep that up to date. It's worth paying the tax to go back have iterations of the document. Maybe it's in source control, whatever, right? Like that might be worth it to you. Maybe you guys don't like architectural documents, right? When I was at a startup, I don't remember writing like docs to go present in stuff. I think that we would mostly brainstorm, whiteboard, we'd build stuff, we'd have code to refer to, have people review the code and talk through it, but a lot less around documentation. Did that make it crazy for onboarding people to it? sometimes, but a lot of the time it was like we're either actively working in this stuff all the time, so we're a small team.

Let's just walk you through it. Or it's like, yeah, that's the legacy stuff and like we don't really touch it if we have to. Like, yeah, we're calling on Billy who's the only person that's touched it in 5 years. And like, full full disclosure, I was that person a lot of the time. And so it either meant like hey maybe this is a good time like to to tell this team like yeah this is some legacy code you guys technically own we don't touch it like ever but maybe this is a good time that I onboard you to it so that you can understand it and come up with the path forward to refactor it right so it's a super heavy tax paid once versus like a a medium tax that you pay all the time or something Right. So you it's just tradeoffs and I think that you really have to look at that um in your scenario.

How we doing for the exit? Wow, no traffic today. What a what a great day. Um okay. Um code being self-documenting. Yeah, like I like the idea. Um I don't know. Personally speaking, I've been programming for 20 something years. Um, I've been, you know, working in software engineering or engineering management roles for 15 years. And, uh, I I think people's perception or what they believe is, you know, self-documenting code is uh, I don't know, maybe very inflated. I I don't know. Like I have this feeling that people often think they write very good self-documenting code. And the longer that systems are around, the the less obvious your self-documenting code becomes. And don't get me wrong, I'm not saying that that means you shouldn't try. And I'm not saying that it means that there's no understanding. I just think that people have an inflated view of their own self-documenting code.

Okay. So, um, with that said, I don't think that you need to like every if statement add a comment cuz my god, uh, if you've worked with LLMs that do this. I'm like, you're the code is like four times as long as it needs to be because you're trying to write a comment on every if statement and for loop and variable assignment. Like, give me a break. like it's distracting from the code again because a lot of the time it's doubling the the actual code that's logic plus a comment that is the logic again it's insane but I do think that comments can be super helpful left in code to explain things that like that this is a decision this is why we went this way right or if there is something that looks like an anti pattern and you're like oh I'm coming across this I'm going to boy scout this and clean it up.

Like that someone leaves a comment to be like, "Hey, just so you know, this is like this for a reason." And if that reason's no longer true, by all means, you know, have at it, but I'm letting you know before you touch this that like there is a reason why. So, I think that kind of documentation can be really helpful. Um I am quite interested in having natural and I don't have a solution for this that I've like uh used in practice but I love the idea of having like code that can be intertwined with uh whatever systems you're using for tracking issues uh or you know wiki pages and stuff like that. So if you're like, "Hey, I have something that I need to refer to in the code." Like if if there's a really good architectural document that elaborates on something like link to it or whatever.

Um I I like that idea a lot. I don't know if I've seen it work well in practice. Uh just to give you a maybe a terrible example, I've seen where people and I've done this even in my own personal projects, okay? or I have um something like a ticket tracking ticket ticketing system or ticket tracking system. That was really difficult to say. Um and like I'm like, "Oh, I I made an issue for this to follow up on it." Like I'm leaving a to-do. And so I put a link to the ticket in the code to be like, you know, let's kind of correlate these things. And then like I don't use that ticket tracking ticket god ticket tracking system and um now I have this URL that points to nothing and no context. So um it can bite you in the ass but conceptually I really like the idea um so that you can enrich the code with I feel like better systems.

I feel like the code itself is not a aside from like some written comments, it doesn't feel like a very rich system for uh like putting diagrams and stuff in or like I love the concept of wiki pages and things like that having uh you know like markdown documentation like it feels like it's a better tool for it but it is a different system right and when you start dispersing things. There's trade-offs for that, too. So, I don't think there's like a perfect solution to this kind of stuff. Pardon me. Um, but those are some of the things I like to think about when it comes to to documenting. Um, yeah, it's I guess the, you know, in a nutshell on that, I I think comments and code are fine. I think it's overkill to try and explain every bit of logic with a comment. Um, I don't think that code itself is a uh the most expressive tool for to for doing more in-depth documentation, which is why I do like other systems.

But then there's tradeoffs for having those other systems, maintaining them, persisting them, uh, migrating things if you like are taking down a system, right? All this kind of stuff. um talked about a lot about tax of maintaining things. So that's just something to think about when you have concepts in different spots. You have concepts in code, you have concepts in architectural documents, you have concepts um in wiki pages, like the more places that this exists, the more tax there is to maintain it. Okay, so just a bunch of things to think about in balance. I just to kind of come back to the startup versus a big tech kind of thing. I said a little bit earlier that like where I work there's a really big culture around uh documentation and architecture and stuff like that and I think there's a lot of benefits to

that but uh I think I always get concerned in general um not just on this I mean but like when things become u a process for the sake of process by the way I was told I don't know which one is a more Canadian way to say it. Is it process or process? But I say it both ways, I think. And apparently one of those ways is is a Canadian way to say it. And I didn't know that. My wife gets that a lot. I don't know which way is what, but she says it one way and people are like, "Oh, you're Canadian." Like I didn't literally I hear both of those and don't associate it with one way or the other. But process process. Um, I get concerned about just doing it for the sake of it because we said that's a rule. Um, I think we have systems in place, processes in place to be able to assist to give us benefit.

Documentation is one of those things. Um, architectural designs and reviews are one of those things. Um, maintaining wiki pages or whatever other internal documentation is one of those things. But when you have these things and they are causing more work, more time, more work than the benefit they offer, like we should look at the the the process or the system, the procedure we follow because I've absolutely seen things where it's like, "Hey, we should do a design dock for this." And I'm like, "Dude, we could talk about this in a meeting for like with a whiteboard for 2 hours, right?" and really just go at it and figure it out and have it recorded and have AI summarize it and we'd be done, right? And like I'm not saying that's the best way to solve everything, but sometimes you then otherwise this design dock goes on for 3 weeks and it's like why are we for what?

Um, so I think there's trade-offs, and we should be flexible, I guess, is my point. Like not just be rigid about the the things we do. Um, I didn't get to AI, but maybe to leave you with a thought on this. Um, I do wonder if the more we have LLMs and things like that that can go through code bases and summarize things. I think it would be super cool for uh, you know, some more advanced AI systems to basically like churn through code and build living documentation on how things are. Um, so that they're the ones paying the tax. I think that would be so neat to be able to have that kind of stuff. Um, and the reality is maybe we don't need that. Maybe if you have AI that can index entire code bases, understand things, have the old uh, you know, architectural documents, interpret those and understand those versus the state of the codebase.

The answer to this is you don't have documentation you have to go search through. You just have AI that you talk to and you're like, draw me a picture of the current state of the architecture. Explain these pieces. and it can just do a really good job because it has all the context. It's way more discoverable because you ask for the information versus you trying to keyword search it. Um, but I could see that being the big direction forward, right? Uh, your onboarding documentation. Cool. Can you have like a I don't know like a an agent or something. Um or even you have something that generates onboarding steps based on on things like I don't know like I don't have the in practice how this works exactly but I can imagine we're not far off from these types of things and I think that would be a a really interesting shift towards this problem that I I see with documentation which is the tax to pay to maintain it.

Um, so yeah, I'm I'm very interested in that. I think that's one of those areas if I just had like like infinite time or whatever and I were like building a business and I like I said like I had infinite time that's something in a in a work environment where I'm like I think we need better solutions for that and I would love to like spend time building some things like that to help uh dev productivity because it is something that I think has been kind of crappy for the entire time I've been working. So yeah, uh, great question, Epic Technav. I hope that helps answer. If there's something more specific, just obviously, you know, just ask a question. I'll make another follow-up video. Um, yeah, if you got questions, leave them below in the comments. Otherwise, code.com, you could submit stuff anonymously. I got other YouTube channels as well.

So, this uh this past weekend, I caught up on some resume stuff, so I'll get some videos out on Devleer Path to Tech. There's my main Dev Leader channel with programming tutorials, AI tutorials, and then the Devleer podcast. you do a live stream every Monday 7:00 p.m. Pacific. The time I'm recording this, that's tonight. Uh we're going to go through the co-pilot CLI tonight. If that sounds interesting, just go check out Dev Leader podcast channel. It'll be recorded and there's also interviews with software engineers there. So check it out. I will see you in the next video. Take care.