Why BSD Documentation Is Just Better Than Linux

Key Takeaways

time for the least spicy take I could ever make on this channel it has so little space it is basically mayonnaise Linux is great and most people watching this channel probably think Linux is great as well I do know there are a couple of Mac OS viewers here and there but that's beside the point every day if you're a heavy terminal user you're probably gonna check out some docs here and there especially if you're not that confident with the command you're trying to use maybe it's a new command maybe you just want a refresher but either way the documentation on Linux is incredibly useful and the vast majority of that documentation is in the form of a man page now in a vacuum the Linux Man pages are great no complaints they do everything they need need to be doing however we don't live in a vacuum we live in a world where other unix-like systems exist specifically the BSD variants and I am here to say when there is a Linux version of the man page and a FreeBSD or open BSD version the version on the BSD variant is going to simply be better there are certainly going to be exceptions where they're either equal or the Linux version is a little bit better but generally the BSD version is just better and you might be wondering well how can that possibly be Linux is so much larger with so many more developers it should be easy to improve the documentation and make it better than what BSD has the answer to why it's not better is one very simple Trend that didn't really catch on with Linux Man pages let's look at a very simple example this is the man page for DD on FreeBSD most of it looks fairly similar to what you're used to this is the man page for DD on open BSD once again fairly similar and this is the man page for DD on Linux now ignore the fact that Linux is going to have more options available a lot of the time when something is implemented on Linux just more features are there that may or may not need to be there now this is the man page for Su on FreeBSD once again looks fairly similar this is the same man page on open BSD and this is the man page on Linux now this is a very long one so we're going to scroll through this one relatively quickly and there we go now most of the stuff you need to know as we established is going to be there like you have your options you have your variables if there needs to be variables but the big difference with the FreeBSD and open BSD version is this examples a lot of Linux Man pages don't have them at all here is a random other one this is stat this is the FreeBSD docs and all the way down here there is going to be these examples on the legs version there are no examples none at all now the thing that really confuses me on how this trend ever managed to happen is the main page for man so this is one of those uh exceptions that has examples so if the documentation for the documentation program has examples how did the other docs ever get made without the examples now maybe it's just me but I think it's a fair argument to make that the man page for man should be the gold standard on how to write a man page and the man page for men is really good it includes every possible section you could ever possibly want even including things that really don't need to be here like defaults whatever the faults are fine I guess that's cool you've got big explanations for every option you've got every option explained with giant paragraphs you've got all of your variables explained in here as well literally everything you need to know is explained here but somehow when writing Man pages everybody skipped this part and what an example for LS might not be that important nothing you can do with this application is going to be dangerous when it comes to something like DD though yeah this can be legitimately dangerous let's say you're trying to write an ISO to a thumb drive you don't want to mistake if and of and you don't want to mistake what drives you are using either or maybe even some of the extra options you want to add this tells you pretty much everything you need to know to properly use DD for what most people are going to be using it for but even with non-destructive tools it can be really useful to have a section telling you ways you can actually use the application and typical interactions you might want to have for example with man here man l less brings up the man page for it man man.7 brings up the seventh section a different way to do that and a bunch of other things that you typically might want to be doing and I know what you're thinking for something like Dash F to search through the main Pages for references of a specific thing you could absolutely go through this and be like okay so what is the option that does this okay it's not this one it's not this one it's not this one it's not this one wait equivalent to what is okay I need to go to the man page for what it is okay what does that do okay so what is display a one-line manual page description okay sure that's what I want it to do but how much easier is it for the user to just have the example here telling you how it's done because you probably want to do it anyway and you don't want to have to go and search for like a 500 line a thousand line man page just to find a single basic option on the bright side though nowadays we do have the luxury of completely ignoring the Man pages and instead relying on tutorials and forums and other stuff we can find very easily online but this wasn't always the case and in some situations still might not be the case let's say you're trying to set up your Wi-Fi and you have no idea what options you need to be looking at but to my delight many third-party app devs completely ignored the trend when writing their own docs or more likely didn't realize the trend ever existed and realized that examples would be incredibly useful even something like my package manager on Arch Linux Pac-Man this has examples and even includes the most important one update the package list and upgrade all the packages this is by no means every use case or even all of the common ones but this is ultimately a good thing for all of the users out there and I encourage anybody out there if you're writing an application and you're writing the documentation unless the application is blindingly obvious in how it works like apt with apt update apt install apt uninstall please include examples of how to use your options it doesn't have to be an example for every single function in fact it really shouldn't be unless you only have like three or four options if you include everything basically you create the exact same problem but now you've created it with examples and in many cases there are interesting combinations that you can't really include all of them in your list of examples but include the main use cases and how someone might use the application or even just really neat features that makes the application stand out from the competition also while I'm on the topic of documentation and third-party apps please can you include local documentation I know you want to have a Wiki for more advanced stuff and that's totally fine but don't make me go to a website just to see any information whatsoever outside of like what the options are and a tiny description and that's gonna be it for me so let me know what you think about examples in the Man pages do you wish this was more of a thing on Linux do you think it just doesn't matter and do you think that wikis are bad and everything should be local I would love to know so if you like the video go and like the video and if you really like the video and you want to become one of these amazing people over here patreon whatever go check out my patreon subscribe link down below that's yeah um that's gonna be it for me bye bye [Music] [Applause] foreign [Music]