In praise of good docs

In this day and age, we’re fortunate to have access to just about any information with a simple web search. While the online treasure trove of knowledge is incredibly useful, it can be a pain to sort through all the content and find something that’s accurate, specific, and up-to-date. I’ve recently had several experiences that have reminded me how wonderful it is to have high quality, easily available, curated documentation.

Car manuals

Not too long ago, my car got a flat tire. I’ve been fortunate enough that this was my first flat, so although I was familiar with the general process of putting the spare tire on, I needed to know the specifics for my car. I went to the glove box, pulled out the manual, and was soon looking at detailed instructions telling me where to find the jack, how to detach the spare, and so on.

I’m sure that I could have searched for my car’s model and found similar instructions, or even a video tutorial, online. However, it was comforting to have documentation that I knew I could trust right there in the car. I didn’t have to remember my car’s model and year, pull out my phone, look through a list of results, or deal with annoying online ads; instead, I was able to simply pull out a book and get to work.

Man pages

I’m currently taking an operating systems class that requires me to do a fair amount of programming in C. In doing so, I’ve taken advantage of the fact that on Linux, basically the entire C library is documented via man pages.

Although man pages often get a bad reputation for their terseness and lack of examples, I still love them. To view the documentation for a particular function, all I have to do is open a terminal and run man <function>. Most man pages follow a standard format, making it easy to find information about the arguments, return value, or potential errors. They’re written by the developers of the language, not by some random blogger. And they’re all entirely offline!

The ArchWiki

My laptop runs Arch Linux because I’m a nerd who loves to customize his computer setup. As a result of my esoteric software choices, I often find that something isn’t working quite right. Thankfully, the ArchWiki’s documentation almost always comes to the rescue.

The ArchWiki can’t address every issue with every program, but it sure covers a lot. Arch’s active community keeps the wiki remarkably up-to-date; if something is no longer accurate, it’s usually changed or at least marked as needing updates. Best of all, the instructions on the ArchWiki are specific to my setup. I have a much greater success rate with the ArchWiki than with other sources online that target Ubuntu, Fedora, or even just Linux in general.

You can’t beat good docs

Online search is amazing, and I use it probably tens if not hundreds of times a day. But you can’t beat a specific, trustworthy, current source of information that you already know exactly where to find.