February 27, 2025 (updated May 15, 2026)
Relax. Take a deep breath. Nothing impedes learning as much as stress and precipitation. Reading programming documentation requires a relaxed and open mind.
Don’t think you’ll find what you are looking for where you think you’ll find it or where you think it should be.
Nope, it’s not where you think it is. Nor is it where it should be. It is where it is. And there is no way around that.
Documentation is imperfect because it tries to distill and explain systems that are inherently very complex and constantly evolving. It attempts to describe imperfect code and is written by imperfect people.
Documentation is often segmented into different sections, creating a sort of progressive immersion that aims to cater to all audiences from beginners to hardened professionals. However, this segmentation can also be very confusing.
It’s curious that people who have experience with programming in general and have worked with the tool/system and its documentation a lot will often extoll how great said documentation is (and in many cases it really is), while beginners will moan and complain about the very same documentation saying how dense, poorly organized, and incomprehensible it is. Neither party is wrong; they just see the same documentation from different vantage points.
This is because…
Diving into docs for the first time is a bit akin to stepping across a forest line into dense woods. Maybe there’ll be a big sign with a bunch of arrows pointing every which way (table of contents) and little flags (hyperlinks) roughly outlining the trails that connect different parts of the forest together, but until you get lost a few times and familiarize yourself with roughly where things are and what they look like, you won’t really know what the forest is really like. The map is not the territory.
This exploration takes time and can be tedious. But getting lost and frustrated repeatedly will eventually compound into a an increasingly clear mental model of the shape and scope of the documentation. You will be able to use this mental model to find things ever more quickly and reliably, and you will be able to leverage the tables of contents and hyperlinks to navigate more efficiently.
Soon enough, the documentation will become like a book on your bookshelf that you’ve referenced and bookmarked so many times that you pretty much know exactly where everything is.
And you’ll be able to plant that “abandon all hope, ye who enter here” sign out front on some forum to flex that you’ve been through the woods and made it out alive :)
There are ways to chart the uncharted territory effectively. Here are the steps that usually work.
Software and its corresponding documentation are always evolving. Docs don’t always get updated as soon as new changes to the software ship. That’s why it might be a good idea to locate and bookmark whatever feeds developers are using to notify users of the latest changes.
Append your search engine query with words like “changelog” or “what’s new” or “release notes” to surface results that will point to a source of that information. Changes are usually published in one of the following channels: official website, official forums, official blog posts, GitHub releases, increasingly and regretfully - Discord, and maybe announced on social media.
Sometimes when you can’t find something in the docs, search the changelogs. Often there will be a little nugget of information that’s absent from the docs but makes all the difference.
Surprisingly, at the time of this writing, Google Chrome’s find-on-page feature remains quite basic and does not allow for case-sensitive or whole-word search. This can be a bit of a hindrance when reading certain types of docs. For example, the CodeMirror documentation is intentionally (I assume) just a long single webpage so it can be easily searched without having to rely on a dedicated search functionality. But searching with Google Chrome is not ideal. CodeMirror uses a type Extension extensively throughout its API and it is sometimes desireable to search when documentation refers to this specifc type. However, the documentation also talks about the concept of extensions in general while referring to them as, well, “extensions” (note the lowercase “e”). So the word “extension” is peppered all throughout the text.
So when we search for Extension and we don’t have case-sensitive search at our disposal, we get back 194 matches. With case-sensitive search we get back 86 matches. A decent improvement.
As of this writing, out of the three major browsers that I have tried (Google Chrome, Mozilla Firefox, and Apple Safari), only Firefox has a powerful find/search feature. Firefox’s search allows Match Case, Match Diacritics, and Whole Words which brings it closer to the capabilities of the search features in Visual Studio Code many developers are probably used to.
So use a browser that has powerful search and it should make your RTFM sessions a bit more seamless.
Documentation explains complex systems, and to explain complex systems effectively and accurately the use of language and choice of words must be intentional and precise. That’s why you should never take any word for granted when it comes to technical documentation. Ask yourself, do you really understand the sentence you’ve just read? Do you know what each word refers to? Every word is an abstraction and a distillation of a concept. Do you understand the abstracted concept well enough to make sense of the sentence?
Oftentimes I find it incredibly frustrating and yet also extremely funny that I can read two lines of text and have no idea what the text is saying. Two lines!
That’s because the language is conceptually dense. So I have to go back to the sentence and read every single word diligently and decompose it into ideas I can understand and visualize. Of course with experience and practice you’ll have an increasingly fluent understanding. Sometimes I come back to sentences that made no sense only a week or two ago and realize that I now understand them almost entirely. The concepts have solidified in my mind and I have a better grasp of them.
So be patient with yourself and know that it’s perfectly normal and existentially okay to not understand things right away. It takes time and experience. Read every word, learn new things, get lost in the woods some more, and eventually things will click.
Anybody who’s read even a little bit of Structure and Interpretation of Computer Programs will have likely experienced this exact process of going from complete confusion to frustration to revelation to clarity. SICP is incredibly dense, but its language is so precise you cannot but marvel at the elegant lucidity that emanates from the pages once you understand. The pleasure of reading SICP is exactly that - being progressively enlightened as complexity is magically unraveled before you with beautiful language… Anyway, I digress!
So this is how I’d recommend one to read programming documentation. Take your time, be patient with yourself, jump around, build a mental model, and soon you’ll know the docs like the back of your hand.
As always, if you have any comments or questions, here is a link to this post on Bluesky. Come say hi!