Tech books vs online documentation: what's the difference?

Editor’s note: From time to time, we will publish guest posts from the independent maintainers who partner with us as part of the Tidelift Subscription. In this post,  Mongoose maintainer Val Karpov shares the differences between the value of tech books and online documentation.

When my dad first started writing computer programs in the 70's and 80's, he kept a copy of The C Programming Language on his desk. Back then, a good reference book was the best way to get unstuck if you forgot how to use printf().

That was before the Internet. In 2020, online documentation is better than ever. If you forgot how to use printf() in C or console.log() in JavaScript, most developers Google for the answer or use autocomplete in your IDE. Tech books aren't the go-to reference anymore, but that doesn't mean that tech books are useless. Today, tech books serve a new, equally important purpose.

The limitations of online documentation

Now that online documentation is the preferred choice for reference material, docs attempt to explain everything about a given project. For example, the docs for the popular HTTP command line client curl list out 383 command line arguments. This huge list is great if you forgot how to use a particular option and need a refresher, but is exceedingly painful if you don't know what you're looking for.

As the maintainer of Mongoose, I've often had to make trade-offs on what ends up in the documentation versus what doesn't. Because I see the documentation as a reference, I err on the side of including more information rather than less. That means there's a significant amount of detail on options and functionality that, in my experience, isn't important for building apps. But the information is there because people have needed it in the past.

Because documentation needs to be complete, it can't omit details that the author thinks aren't relevant. Furthermore, people rarely read documentation from start to finish. Most of the time, developers end up using the documentation as a reference when they run into issues. So docs need to provide all the relevant details, with the assumption that people with all sorts of experience levels can jump into the documentation at any point.

Books provide perspective

Curl's 383 command line arguments are necessary because curl is more than just an HTTP client. But, if you're just looking to use curl to send some basic HTTP requests from the command line, the 383 options hurt more than they help. Because I find myself always forgetting the curl arguments I most commonly use, I took the time to write a blog post about using curl for API requests. This blog post is far from a complete guide to curl, but I think it provides something that's equally valuable: an easily digestible perspective on curl.

My new eBook, Mastering Mongoose, provides a similar perspective on Mongoose. It describes how, in my experience, developers should think about building apps with Mongoose. Rather than listing out all the functionality Mongoose offers, it explains the fundamental principles of Mongoose and how to apply them when building an app. Mastering Mongoose also comes with 4 sample apps that demonstrate how to apply the book's principles.

Mastering Mongoose is meant to be a guide that provides perspective on how to build Mongoose apps, rather than a complete reference explaining all of Mongoose's functionality. What the eBook omits is as important as what it includes. I had to make several controversial exclusions: no aggregation framework, no transactions, no read preferences.

I excluded these topics because, in my experience, they're not essential for building apps effectively with Mongoose. Many developers disagree, and that's fine—that's why these topics will continue to be covered extensively in the documentation. Mastering Mongoose is about providing perspective rather than serving as a reference, and that requires being more opinionated on certain points than the documentation.

Moving on

Tech books today serve a different role than they did 50 years ago. They provide a guided, opinionated perspective on how to use a library or framework, rather than serving as a reference for when you forget a method signature. Documentation needs to explain almost every bit of functionality the module offers, and needs to be accessible for people that hop into the middle of your content from Google looking for a quick fix. A book can be more opinionated on what it includes versus what it omits, and can provide a more guided perspective than documentation.