 Let's talk about documentation. What is the right amount of documentation for a software project? Because you've got two extreme ends of the spectrum. You've got the one group that does zero documentation, absolutely no documentation. So think of something like Sucless Software. The Sucless guys, they don't document anything. The source code for their software, that's their documentation. If you want documentation, you go read the source code for that particular piece of software and hopefully you understand the programming language and what it's doing because that will tell you everything you need to know. That's one extreme and then the other extreme is the groups that document everything. Every little detail, every little minutiae. They have an orgy of documentation and that's another extreme and I find both of those kind of unappealing. Obviously, I don't like not having any documentation. I also don't like being overwhelmed by documentation where they've documented so much little detail that especially the big questions, the common questions that I'm looking for answers for. Sometimes it's hard to find those answers because they provide so much of this other documentation about these really niche use cases. Is there a good middle ground? What is the right middle ground for documenting your software? This has been more and more a topic that's been on my mind here the last few months. The more I get into packaging some of my own programs and I get people opening issues on my GitLab support requests for some of my scripts and some of my programs and of course I try to document some of my stuff but how much documentation do I need to provide? I learned early on that just putting something out there with no documentation was a problem because you're going to be flooded with questions like really basic beginner level stuff. How do I install this? You didn't tell me how to install it. What does the program do? If you don't at least tell people how to install your program and maybe give them a one line description of, hey, this program does this, then all they're getting is a GitHub or a GitLab repository and they see some source code but if you don't tell them, just spend like five minutes writing a quick read me on the basics. If you don't do that, people are going to ask you about it so you have to give them at least something but do I need to detail every little minutiae? Because the more and more I spend on documentation, the more it gets into my head that sometimes I'm documenting really niche stuff that nobody has ever asked me a question about but in my mind I'm thinking well somebody might run into this problem, somebody might run into that problem and I'm documenting all of this stuff again that nobody had ever asked me about. Am I wasting my time with documentation at that point? Is that time that could be better spent actually working on improving the piece of software adding more features, doing bug fixes, things like that? I know myself and probably most people that use computers probably have it in their minds if you've ever went looking for help documentation on anything. You imagine that the good projects offer really good documentation, extreme amounts of documentation and that those projects because they have such good documentation it probably helps them, they don't get as many support requests, right? They don't get as many issues opened on their GitHub or their GitLab or on their IRC channel or Discord channel or whatever support forms they happen to have, is that actually true? I don't think that is because let's take Linux distributions for example. What Linux distribution has the absolute best documentation out there bar none? Arch Linux. Have you seen the extreme amount of support requests on like the Arch subreddit and the Arch forums, the Arch IRC chat channels, you know, there are plenty of people opening support questions on those particular support forums just as many people that are doing this on Ubuntu or Linux Mint forums and Fedora forums and things like that. Did the Arch Wiki actually solve any real problem? I would say no, I love the Arch Wiki, I'm glad it's there. But does it really have that big of an impact as far as not having to interact with people on forums or in chat rooms as far as support requests? No, I don't think it does. Now one of the things I do love about the Arch guys is because they do have such fantastic documentation when people come to them on their forums or on their IRC, you know, they will actually point them to the Wiki, you know, the old RTFM, you know, read the effing manual, you know, it's always the answer and I know people get put off by that and for me, I don't mind that as long as the documentation actually tells me what to do, I don't mind people telling me to go read the documentation and I understand another thing is most people assume that somebody is just going to give them the information. I'm going to ask you a question. You're going to give me the answer. I'm not going to go do any research on my own. I know that kind of puts people off. That's why they have, you know, these wikis for these Linux distributions and these man pages for your particular software on your Linux distribution. But let's be honest, 99% of your desktop Linux users don't read any of that stuff. Most of them have never opened a man page in their life. They did. They probably didn't actually read it. They looked at it for about two seconds and then quit out of it. And I'm not reading that thing. Most people are not going to go read like detailed wiki information on like the Arch wiki or the Gen 2 wiki and things like that, which are fantastic resources. Most people are not going to do that because that requires them to actually sit there for a few minutes and try to read something, try to understand something, and it might take them a minute to actually find exactly the piece of information they're looking for in that wiki article. Why am I going to wait for that? Let me go ask somebody and just have them immediately give me the exact answer I'm looking for. That's the laziness in most people's minds and I understand that's why a lot of people get put off in support forms. But as somebody that has some software on my Git lab, for example, I get questions all the time and I'll be honest, most of the questions I get are rather ridiculous questions. I'm going to just put it out there. I have people opening issues that have absolutely nothing to do with my software at all. Like, hey man, this question you just asked me has absolutely nothing to do with the repository of software you're currently asking this question in. Like you're asking questions that have absolutely nothing related to this. So I understand why some people in support forms and in support chat rooms kind of get frustrated and just tell people to RTFM, hey man, go read the documentation, you'll work it out. I get that. But the RTFM response only works if you are that extreme documenter. Like if you're one of those projects like Arch Linux that has an orgy of documentation, right? They're on one extreme. Of course, you got the other extreme. Like I said, the Suckless crowd, they don't document anything. And of course, that means when you don't document anything, you probably actually get less support requests. The Suckless guys probably get far less support requests asked because they're not going to support you anyway. I mean, they didn't even bother writing basic documentation. They pretty much have told you, we don't care about noobs. We don't care about novices. You go read the C source code for DWM or whatever piece of software. You go understand that C code and you'll understand the software. Don't ask us any questions. And of course, that's arrogant. That's elitist. That's very smug, right? And but that's the way they've chosen to be because they just don't want to deal with people asking them any questions. For me, I think somewhere in the middle is the sweet spot. I don't know where. And of course, that's part of making today's video is I would love some input from you guys, especially some of you guys that are part of major projects. Maybe you're on the documentation team for some of these Linux distributions out there. What is the right amount of documentation? Obviously not having any causes major problems. And then of course, having an extreme amount of documentation while it sounds good, that really doesn't reduce any kind of workload as far as the amount of support request you get anyway. And I have actually heard from plenty of Linux users that tell me the Arch Linux Wiki is confusing. Like there's so much documentation. Like if you go read the Arch installation guide on the Arch Wiki, it points you to a hundred different places all over the Wiki. Like the bootloader section talks about Grub and it links you to this Grub page on the Arch Wiki. And the Grub page is massive. Are you really gonna read all of that just for that one minor part of the installation installing the bootloader? You know, that's what people talk about when they talk about things like a orgy of documentation and how it can be a real negative. When you look at Linux man pages, you can really see these two different philosophies, the people that really don't care about documentation and the people that go to extremes. If you go read some man pages, they are literally just a one line description of what the program is and maybe who created the project, that's it. And then you go read other man pages like some of the GNU man pages. Like if you go read the man page for the GNU find command, the basic find command that's part of the core utils or actually it's part of the GNU find utils package. The find man page is massive. It would take you all day to read that thing and probably months to understand everything that's possible within the find command because it's a very powerful command. And that man page is so detailed. It's a fantastic man page. Nobody's gonna read it though. It's too long. It's got too much stuff packed into it. Or the man page for the bash y'all, GNU bash. The bash man page, massive. It's like reading a book. Nobody's going to read that thing. At least not normal people. Most people are not gonna read a man page that complicated. And I see actually a lot of professional developers actually talk about this. That documentation, is it good or can documentation sometimes be bad? And I've actually seen people actually make the claim that sometimes documentation can be a negative. I think one perspective I would like to hear from is from those of you that are not programmers, not developers, not long time Linux power users. You're just regular desktop computer users. You have some basic needs, but sometimes you have to troubleshoot your own problems. What do you think about documentation? Do you like reading documentation? Do you hate reading documentation? Do you like it when there's not that much documentation? It just answers a few of the most common basic questions or do you like these detailed instruction manual kind of documentations? Let me know in the comments down below. Now before I go, I need to thank a few special people. I need to thank the producers of this episode. I need to thank, Dustin Gabe, James Met, Maxim, Michael Mitchell, Paul West, William Bowen, Homey Allen, Armoredragon, Chug Commander, Rangry, Diolky, Dylan Marsh, Drum, Erion, Alexander, Peace, Arch, and Fodor, Polytech, Realiteats for Less Red Private, Steven, Tools, Devler, and Willie. These guys, they're my highest tiered patrons over on Patreon. Without these guys, this episode would not have been possible. The show's also brought to you by each and every one of these fine ladies and gentlemen, all these names you're seeing on the screen right now. These are all my supporters over on Patreon because I don't have any corporate sponsors. I'm sponsored by you guys, the community. If you like my work, I'm gonna see more videos about Linux, free software, open source software. Subscribe to DistroTube over on Patreon. All right, guys, peace.