Does Software Documentation SUCK or... Is It Just Me?

Transcript is auto-generated and may contain errors.

Hey folks, we are going to a message on Instagram and this one's about documentation. I think it's a really good question. This one says, "Is struggling with docs normal at the beginning? Some I understand fine, others I'm completely lost. They show examples but don't explain why you pass certain parameters or what the function can actually do." And then they said that they've been using AI to fill gaps uh with some docs or when like if yeah if they're feeling lost. And then they're saying like do does your comprehension improve as you develop more or when you're more experienced does it still happen? So great question. Um I it's interesting. I think docs I think documentation is helpful but I think it's a catch22 kind of thing. I think that uh good docs are helpful. It's hard to have good docs though and uh maintaining good docs is a lot of work.

I'm hoping that over time with AI tooling that maintaining good docs is no longer as difficult or that they get stale because that's the biggest thing with document. Well, one of the biggest things with documentation is like the rate at which everything else changes is generally much faster than the rate at which documentation is kept up to date. Or you run into these systems like this person's describing. Or maybe you have up-to-date documentation all the time, but the type of documentation you have is like like here's the the names of the parameters with like a a you know oneliner description. It's like user ID and then the description is the ID of the user and you're like great. Thank you so much for that that help. Um, so you can get these API docs that are kind of like it's just a transform into like sentence form or something or into like a table versus just having it in the code, but the the value out of that is like very very low.

So I think that you have situations where we want documentation that's up to date. We want documentation that's helpful and clear and offers examples and explains why, but like all of that stuff is more than zero effort, not only to create, but to maintain. And then the more things you have, there's more and more of like this tax you have to pay to maintain documentation. Um, keep it up to date. Right? So for this person, I think it's interesting because part of what they're experiencing right now is like, "Hey man, like how much of this is me and how much of this is maybe like documentation that sucks?" And um I think, you know, there's probably a little bit of both, but I I would say that there's probably a lot of documentation that's just not good. Like checking a box to say, "Look, I have docs is like step one.

But having good documentation is a whole different different world. And in like all of my years of development, seeing good documentation to me is pretty rare. Um, okay. Like as an example, I'm a .NET developer. MSDN is where and like Microsoft Learn now or like where Microsoft has a lot of their documentation especially for like C# development. But like historically that stuff has sucked. And it would be the same thing where like you'd go onto Google, you're searching for something and you're like, "Oh, great." Like there's a hit in the documentation and you open it up and it's like this this page and you're like, "Great. I can't wait to scroll to the part that tells me what's up and you get to a point where it's just like a list of methods and their parameters and like it's just not it's not helpful. Like I can see the same thing with IntelliSense in Visual Studio like thank you so much for wasting my time.

But over time, that stuff's gotten a lot better where uh not every page has like an in-depth example or something, but it's more common now that when I go searching for that stuff, unless it's kind of like at the, you know, the edge of uh like obscure stuff in C and a lot of things now have examples where you can see it being used in code. So like even that stuff's taken a long time and it's not perfect. Um so yeah I think that the bar is uh the bar is non zero but it's pretty low for at least generating documentation but the bar for high like for useful documentation is high in terms of the effort that has to go into it. Um so I don't think it's just this person.

I think that yes, of course, like um having more and more experience, not only will this become more obvious that there's just a lot of documentation that's trash, but in terms of being able to understand it um because when you do run into documentation with some uh some examples or other verbiage that's not just repeating the parameter names and stuff like yeah, like the more experience you have, the the more you can uh interpret this stuff a little bit more effectively. But I think it's a great example of using AI to help with this kind of stuff. If you run into documentation where the the actual sort of like API that they're listing, even when it's not like uh helpful descriptions and stuff, it's just like the parameter names and the the types and stuff and the method names. I think that having AI do some explanation for you um is definitely a value ad.

Tricky part is like it's not perfect because if it's just if it doesn't know actually what the code is doing and it's just trying to give you information based on the method name or the API name like it's also kind of guessing at what's happening. Um, unless you were to if you have the whole codebase, let's say, depends on how you're like what docs you're looking at, but if you have access to the whole codebase, you could perhaps go ask and I guess depending on how you're prompting AI. But if you're I guess my point is if you're going to ask it on the surface what some API does and it doesn't have access to anything else other than what's like directly provided to it. It has to guess at what it's doing and it might make like informed decisions. It might do what you're trying to do just quicker um which is helpful.

But if you are in a position where you have the docs, you have the code base and you're like running off your desktop or something uh in a console or in your ID, you might be able to say like and go look at the implementation and then like make um you know provide you better uh details about what some API is doing. So I I think that it there's the possibility that it can do better. Um which is great. I think I think that is a good use of it. Uh but again like having it's easy to have confidence in something that you know like it's just looking at what a method name is and it tells you confidently oh yes clearly here's what this is going to go do. It might be right but it also might just be making up and then you're you're reading this thing telling you confidently something and you're feeling confident about it.

But I do think it's a step in the right direction. I think we can use AI to help scaffold documentation. Again, it might be making up when it's generating it for you, but I think it does a can do a lot of the heavy lifting. So, I think we should try to wire that stuff up more into our documentation so that instead of just getting like here is the method name and the parameter with the parameter type, here's like example code of it being used. And then maybe we have to go clean that up and there's still some work for us to do. like there's still a tax to pay but we can reduce the tax and that way we get better documentation created over time. Um so I think yeah I wouldn't say like hey no man it's just you but um at the same time sure like this stuff will will get better.

Um yeah like I I like to to finish out this video like I I still run into to documentation and have challenges reading stuff. I do think that having examples um of use cases in code, I think having explanations behind things is helpful. So if you in if you want to see an opinion of what I think is very good documentation, um and I've said this especially on my main channel, Dev Leader, um there is a caching library that's third party and uh met the met the creator and the maintainer and he's awesome. His name is Jody Denetti and the library is called Fusion Cache. If you want to see what I consider very good documentation, go check out Fusion Cache on GitHub and check out his documentation. And I think Jody has done a tremendous job because like if I were to go read the documentation, it's like it's going to sound kind of funny because it's you're like what do you mean by this?

But like it's actually enjoyable to read. So, he's written it in a way that doesn't feel like you're being, you know, punched in the face with technical like bull crap. Like, have you ever tried to read like a uh a license agreement or something and you're like, "Wow, that's lawyers speak top to bottom. Like, I don't want to touch this." I think sometimes when we read technical documentation, you're like, "Hey, that's, you know, that's software developers speak top to bottom and like kind of feels like garbage." He's done a really good job of like writing like there's you get a little bit of history, you get a little bit of why, you get a little bit of how, you get examples, and it just reads nice. So, I'm the kind of developer where, you know, if if I'm in Visual Studio and I'm building stuff, I'm doing trial and error.

I'm just bashing at the keyboard trying to get stuff to work because like it that's kind of fun for me to explore. But also, there's a trade-off there, right, where you're just literally wasting time. Um, but I'm I'm, you know, I don't go to documentation right away, and I probably should do it a little sooner. But with Fusion Cache, every time I've had to go check out documentation, I'm like, "Hey, this is this is great." Um, so in my opinion, if you want to see a good example of it, Fusion Cache, Jody Detti, check it out on GitHub. Um, this is not like sponsored by a open-source library. I just think it's a really good example of it. Um, so yeah, check that out. Uh, but yeah, I, you know, for this person, it will get better over time. Uh, because you'll be getting more skilled.

It will likely get better over time because we'll have AI tooling for helping us generate and interpret documentation. But it's not just you. We are, you know, historically pretty bad with documentation as software developers. So, hope that helps. Um, you know, stay with it. keep plugging away and uh if you have questions that you want answered, leave them below in the comments. Otherwise, send them in to code.com or find me on any social media platform either as code commute or dev leader. Dev leader is my main sort of like social media handle. Send me a message. Happy to try my best to answer. See you next time.