The Art of Skimming Through Documentation

TL;DR: The title is already self-explanatory, but nonetheless: Skimming through well-written documentation is one of the best ways I know to discover new techniques and tools. It is easier and can sometimes be more effective than straining your brain attempting to decode someone else's code for the purpose of learning.

This could have been the perfect opportunity to begin with the classic: This is something I wish I knew as a beginner. However, in my case, I believe I was already doing this even as a beginner. I don't recall where I picked it up, but I knew two things that might have pushed me toward that edge:

1. There is a lot to understand in this tech stuff.
2. Understanding any topic requires reading about it first. Reading may not be enough, but it is a prerequisite at least.

I'm sure you've already heard countless times the classic go read the docs advice. Some colleagues might have even shouted that to you. And I can reassure you, they were right. Reading documentation is crucial, but I'm here to advocate for something else, similar yet different and also complementary - skimming through the documentation.

What do I mean by skimming? The basic workflow for most is as follows: use a tool, encounter a problem, Google for a solution (or refer to the documentation if you're more experienced and if it is applicable), and repeat the cycle. This approach works fine and you'll eventually become proficient with that tool after repeated use.

But let's imagine this: the first time you use the tool, you skim through the docs. You speed run it, reading every chapter title and subtitle, and maybe even a few lines of each paragraph (if you have time and the doc isn't too long, you might read the whole thing). The first thing you'll gain from this is a sense of possibilities. You'll get a general overview of what you can do with the tool, and a deeper one than if you had just read the readme or tutorial section. Who knows, perhaps while reading, you'll discover a new approach or pattern, or even a new tool(maybe a dependency of that project). I can give you two examples of when that happened to me:

• I gained a better understanding of concurrency in Python while reading the FastAPI docs.
• I discovered the PostgreSQL LISTEN/NOTIFY protocol while reading the Procrastinate documentation.

The patterns and tools that I discovered while exploring the deeper parts of tool documentation often bring me value later on. You can also view skimming through the documentation as a form of preliminary research. Doing so will assist you in acquiring enough background knowledge to make using the tool easier and, as they say, effortlessly connecting the dots.

Small aside, this "A.I." trend is taking away the opportunity for a lot of people to appreciate well-written documentation. Copilot and ChatGPT are great for getting quick answers, but they usually keep you on a surface level of understanding (unless you continuously prompt them for deeper knowledge, which I doubt most people do). These tools are lowering the barrier to entry and increasing productivity for developers, but at the cost of a deeper understanding of the tools they are using. The best developers I know are the one with a deep knowledge in their craft. But who knows, maybe we will all be obsolete in a decade and none of this will matter.

A side benefit of skimming through documentation is increasing your chances for those moments when you think, Haven't I read something on this somewhere? It's unlikely that you'll remember even half of what you skimmed through, but that's not the point. The goal is to potentially discover new techniques and tools and increase your chances for these déjà vu moments when you stumble upon an issue that might be solved by something you already read in the past.

Small Tip: Reading code can be challenging, especially when dealing with large projects written by others. However, even if you can't understand the code itself, take a look at the requirements or dependencies - you might find something valuable there!

I hope you have learned something from this article. What I describe here may not work for you or match your style of learning, and that's fine. I'm just making you aware of this option in case it was not already the case. And if you are already doing this, great buddy! Just know that you are not alone.