Look, whether you’re a Linux user, a hardcore webdev, or even an IT technician, docs are a part of all of tech, but few people actually understand how to read them and more specifically absorb them.
If you prefer to consume this article as a video, check this out!
But Oscar... 😕
Now look, I hear you saying “but Oscar, I just read the whole Rust book” or “I just read what I can’t figure out on my own – people don’t know how to read documentation because these 20 page documents aren't necessary anymore”, and we’ll get to that in a second.
Because yes, you’re right, documentation comes in many forms – READMEs, autodocs, and even videos (yes, Google makes videos sometimes instead of writing documentation).
And as we get better at documenting our stuff, the need to have the patience to read through that 20 page document drastically decreases.
But lemme ask you this (and I want you to actually, truly, think about this): are you reading the docs, or are you absorbing them?
This is what you should be!
Can you recall everything that you just read about Rust or a Linux tool or some other technology that you’re learning? Well, probably not, and that’s normal, it’s not bad.
But you probably can’t recall as much as you should be able to. See, a lot of us get sucked into this notion of reading without comprehending – and this brings me back to what I just said about reading docs instead of absorbing them.
Absorb it! 🌊
Documentation, and really all forms of writing, are meant to be thought about and understood and comprehended, and when you just graze over a bit of writing, you’re not actually doing anything of that nature.
And this makes sense. Your brain isn't like your Linux, unfortunately. You can’t just throw something at it and expect it to perfectly copy everything down – and you probably know this.
Now there are a lot of strategies to mitigate this and we’ll talk about some in just a second. But first let’s talk about why – why should you care about being great at reading docs?
And don’t worry, I’m not gonna try and sell you on this idea like your high school counselor telling you that reading is a skill that employers value.
Let me actually explain to you why you should learn how to actually absorb the information from the documentation that you read.
Why? ❓
Why, oh why, should you actually care about your documentation reading skills?
Because Linux 🐧
Firstly, Linux (and any widely used technology that isn't dead simple).
All of the try hard tech people, myself included, want or need to use Linux, but I don’t think a lot of people are aware of how much time it takes to learn to use Linux. And not just time, but effort. If you’re at all aware of how complicated Linux can get, you’ll know that there’s a lot of documentation reading involved.
And well, if you skim everything that you try and read or watch, you’re gonna be forced to re-read a lot of what you just read. This is an energy drain: it’s demotivating, tiring, and it really kills the fun of Linux, or again, whatever tool you’re trying to use.
I myself can confidently say that I’ve done this plenty of times: I skim over the initial manpage and then spend the next 20 minutes wondering why I don’t understand the CLI or program that I’m trying to use.
Just look at this documentation!
And as I mentioned, the Linux analogy can be applied to everything. Any language, framework, or library worth your time is going to have a considerable amount of documentation behind it, and if you can’t effectively absorb it, you’re kinda cooked.
Tutorial hell 🔥
Secondly, this is the best way to get out of tutorial hell.
If you’re not familiar with tutorial hell, it’s basically this state that every tech person reaches at some point. You’re advanced enough to do your own projects, but you’ve been following YouTube or FreeCodeCamp tutorials for so long that you don’t want to and don’t know how to build a project without a narrator guiding you.
By the way, if you’re in this right now, let me know. I’m curious.
Anyways, being fluent in docs is one of the best ways to help yourself out of this state, and even if you’re not actively in this state, you might find yourself or a friend there at some point, and this can really help.
For you! 🙂↕️
Thirdly, this is kinda obvious: this is for your own benefit.
The more efficiently you can absorb information, the more time you have to do the fun stuff, like coding, and getting stuck on really stupid bugs… that’s about it.
Not only does this benefit you, but it benefits everyone around you.
But anyways, this is the big one: break it down and interact with the material. Let’s take the Rust book for example. I’m gonna start with this section about generics and ohmygodthat’samassivewalloftext. But hold on; let’s not just read it. Let’s break this down.
An example/usecase 🚩
In this case we’re gonna try summarizing, but this could totally be adapted based on what I’m learning and what I’m doing. And by the way, please don’t use Chat Gippity to summarize – that completely misses the point of what we’re doing.
Ok, first we’re told that generics are abstract tools.
Then we’re told that functions and structs and a few other things can work with generics.
There’s also this tidbit about traits and lifetimes but we’re gonna avoid that for now since it’s not really on topic.
However, it should be noted that if the Rust book includes traits and lifetimes in a section about generics, we might also want to consider how they’re connected.
Anyways, we broke down the problem. Now let’s interact with the material. When it comes to programming languages like this, I tend to enjoy just splatting something out into my editor and seeing if it's anywhere near right. Now you’ve probably seen generics before, but let’s act like you haven’t.
It's not working! 📉
Ok, so I know generics are defined with the little pointy brackets anywhere we want multiple data types to be accepted into a parameter of some kind, so maybe when we define a type in a function parameter we can add a generic… oh that’s not working.
fn my_func(param: <T>) {
// ...
}
Let’s pause for a second. This is where we should probably stop, go back to the Rust book, and do what we just did again: break the problem down and interact with the material. Ok, our problem is that we don’t know the correct syntax for generics. Let’s look around… and oh, we just found a sample function definition with generics... and that makes a lot more sense!
Ok, so it looks like we put the generic out here and then just include the type, T in this case, in the function parameter itself. And look at that, it works! (For the nerds in the room, yes, I know this isn’t a complete example (kinda))
fn my_func<T>(param: T) {
// ...
}
Hold on 🫷
Now stay with me for a moment. You might say “oh but this doesn’t work for everything” but it does. This works for the documentation of anything – even the country I live in (and no, I’m not joking, you could totally do this with the law).
But look, my point is that you probably haven’t been doing this, but you definitely should be. Don’t just read a bunch of documentation and try to commit it to memory. Actually think about it and interact with it and all that fun stuff.
Bringing it full circle ➰
And let’s bring this full circle. Remember at the start of the post how I noted that you probably can’t recall everything you just consumed and/or read.
I did, trust me!
And if you completely forgot about this, well, that proves my point. And if you didn’t, awesome. But let’s expand this idea to what we just did. Just think for a second, what did we learn about generics in Rust?
Actually learning 🏫
If you said “it's for multiple data types and they go in pointy brackets outside of a function”, great. And don’t worry about the fact that this sounds wildly unorganized. That’s fine.
What actually matters is that you understand it and can actually recall the information that you just absorbed.
There’s a lot of science and psychology behind why this works, and for many reasons I’m not going to cover that on this channel. But if you’d like to know more, I do recommend Benjamin Keep. He makes quite a few very well researched videos on this stuff.
Benjamin Keep, PhD, JD - YouTube
Insights into learning, science, and society. For teachers, students and the science-curious. I’m a cognitive scientist specializing in learning and instruction. I focus on how to develop expert reasoning skills and what the heck this beautiful, fascinating thing called science is. You’ll also find videos on social science research methods and bigger picture stuff, like how social systems produce scientific knowledge and why that knowledge sometimes goes ignored or misapplied. I have a PhD in learning sciences and technology design from Stanford and a law degree from Cornell. You can read more at www.benjaminkeep.com and sign up to my email newsletter there.
youtube.com
Another option 🛗
But hold on, there is actually something else you can do here. If you’re still confused about something that you’re learning, try breaking it down and summarizing it, then building it back up in your own words.
We can do that with our previous statement like so: “Rust generics allow for multiple data types to be handled through a singular function parameter, and the type parameter is defined in the angle brackets outside the function”.
But do what makes you happy and do what makes you comfortable with the documentation that you just read.
Bad documentation 📜
One other thing I wanna address is the following: how do you deal with bad documentation?
This is adamantly the fun part – or, not so fun part, I guess. When you come across bad documentation that’s poorly written or lacks appropriate content, this whole “magical” strategy kinda breaks.
Imagine if I couldn’t quickly find that sample function with generics from the Rust book. I would be dead in the water until I found either an example in the book or an example from relevant source code elsewhere.
And I’m gonna be completely honest here: there’s no one right answer for how to handle atrocious documentation. That being said, I think the best thing to do and the natural response is to take to GitHub issues or the forums and ask a question.
But usually, especially when we’re talking about Linux or some other well used technology, this isn’t a problem. And that’s kinda why I’m not addressing it so heavily.
Oh well. 🤷
So yeah, you’ve probably been reading documentation incorrectly the entire time.
But you might not agree with that, so let me know if you don’t, and let me know how you read documentation.
Top comments (20)
What about documentation that is focused on theory mostly or thigns that are hard to get your hands dirty with it kinda stuff.
In those cases sometimes summarizing or dividing the text doesnt works.
For example, complex architecture design patterns or architecture and tools around it,
distributed systems , performance related stuff etc.
How do you guys learn these??it often requires a lots of concepts and codes that are hard to understand what it does..
Even then, you can still break it down and try to understand it.
Take the BitTorrent Protocol for example:
That being said, I totally get it. This doesn't work perfectly for every single thing.
Great as always. - And there’s no way you got a sponsor like brilliant.
I was also very surprised! Grateful nevertheless, but still.
tl;dr.
Actually had to make an account after years of lurking on dev.to, but I just couldn't resist... 🤣
But, having worked with Linux from before package managers really became mainstream, I've read my fair share of documentation (and I've received my fair share of, "rtfm"-responses on forums, often even if the info I sought wasn't in the documentation).
Documentation certainly is important, though, this way you lay it out is not my method.
Firstly, generally I prefer reference documentation vs user documentation. And I also don't retain much info just from reading documentation if it's not applicable to what I'm doing at that moment. In my mind it feels like trying to scoop water into a bucket using a colander.
If however I want or need something, I am really good at finding the info required. Years ago I needed to write something in postscript, and the blue book (and its green predecessor) was exceptionally useful, though I didn't read it. I just used what I needed.
We all tick in a different way. For me, I start work with a reference manual on a second monitor. Can't remember ever reading significant documentation before starting.
Counter point: write documentation that doesn't suck.
Most documentation for software is an active non-example for how to write documentation. At best it sort of makes sense if you already understand the software. Most documentation is full of circular references and completely undefined terms.
I really like this! Great read!
I don't always read the docs before starting on something if I already have a lot of knowledge of the language it's written in or thing similar to it. If I run into issues, I go looking for docs! Sometimes I also see if AI can solve it (but AI often does things in a way that works but not optimally).
Yeah, that's also what I do sometimes! It just depends on what I'm learning/using.
Interesting. Thanks for sharing!
Such a relatable breakdown...
Can't agree more on this. I don't get it why people don't read docs as much. You can literally get the whole idea of the project once you read it thoroughly
How I learn is to just wing it after reading the docs for something I need. I like discovering things I didn't know only after I've tried my own solutions for a bit, it's the only way I retain info
The smallest details in these post make the one who created the documentation learn about it again ..
Well organized and written .. Thank you for this