Is documentation not supposed to be read in its entirety?
Posted by ElegantPoet3386@reddit | learnprogramming | View on Reddit | 29 comments
So, I think when I was trying to read the arcade docs to figure out how it worked to start making physics sims, I treated the docs as a textbook. In that I started at the top and kept reading downwards to try to learn all about how arcade worked.
But, I'm noticing now whenever I want to use the arcade docs on how to do a specific thing, like find out how to make the physics sim recognize keyboard inputs, it takes much shorter time and also I have a higher chance of finding what I'm looking for.
Is that how docs are supposed to be used? Like to find out if there's a function for a specific problem you want to solve?
SilverTM@reddit
Results are the only thing that matter. Learn what you need to get the job done.
highjohn_@reddit
For the most part no. That would be pretty hard to just read through all the docs and commit to memory. Read the relevant parts for what you’re working with. Over time you’ll fill in the knowledge etc
grantrules@reddit
It's worthwhile to skim, often. Depends on the size/scope of the library, but I'll browse docs and maybe make a mental note if I find a function or something I think seems useful.
Aqus10@reddit
Cant agree. Sometimes you need to read the whole book to know specific thing even exist.
caboosetp@reddit
That's shit documentation then. Everything you need to know to start should be in the intro, and anything you need for the problem you're solving should be readily mentioned in relevant parts of the documentation.
FlippingGerman@reddit
Manuals can be good to read through entirely once you already know the basics, or better. You can find all the nice details that can help perfect a skill. Most of the time, no, just skim it, unless injury or death may result.
our_operations@reddit
There's definitely different flavors of documentation and they're not all meant to be read cover-to-cover, so to speak. In general, whenever I have docs in front of me to read I take one or two of the following approaches:
Framework or library docs, example React docs - if you're just starting to learn about React, I'd say read through anything that is 'Getting Started' like a textbook. There may also be summary documentation at the beginning of each section that might be helpful to you like
what do hooks do?how can I avoid unnecessary renders?, things/topics like that.Most everything else can be thought of as encyclopedia/dictionary entries that yes, you can read them all but you probably won't retain the info enough later to not need to review the relevant docs at that moment. Don't try to memorize all the hooks and what they do ahead of time, just the most used ones in your experience or vision. Have a slow look through the titles of pages and try to mentally bookmark anything that might be interesting to read through later on, but don't try to memorize anything especially if you don't need it then.
In a nutshell, you're going to be wayyyy better off now and in the future being able to find what you need in documentation when you need it, rather than trying to commit irrelevant info to perfect memory recall so that you can feel like a memory wizard when you need it
Select-Reporter5066@reddit
Yep. Tutorials are for the couch, API docs are for the crime scene. Skim enough to know the nouns, then search when you're actually trying to make the keyboard input behave.
AlternativeWear2879@reddit
Most docs are 70% API reference (lookup material) and 30% concepts. Reading cover-to-cover wastes time on the reference part. The pattern that worked for me: pick one concrete thing to build, read only the "Getting started" and "Concepts" pages first, then ctrl+F the reference when stuck.
I learned this trying to read the Play Developer API docs front-to-back ... gave up around page 12 and built the actual script the same evening by skipping straight to the reference. The doc is a map, not a textbook. What are you building right now
ElegantPoet3386@reddit (OP)
Not building anything too much, just a basic physics sim since I like physics
You can see what I’m talking about here
https://youtu.be/Jqh93T_y0vA?si=AdV7yLLmmWef6i6c
nicoloboschi@reddit
Comment 3 has a great breakdown of how to approach documentation. Hindsight's documentation follows a similar pattern, with getting started guides, conceptual overviews, and a detailed API reference, all geared toward different learning styles. https://hindsight.vectorize.io
Select-Reporter5066@reddit
Yep, docs are usually more like a map than a novel. Skim the shape first, then deep-dive when the bug drags you there.
opentabs-dev@reddit
yeah you basically figured it out — docs are mostly a lookup tool once you've skimmed the concepts page. one trick that helped me: when the docs are bad or vague, just open the source on github and read the function signature directly. you'll often find params or behavior thats not even documented. cmd+f is your best friend too, dont scroll docs linearly looking for something specific.
wokka7@reddit
Im not a programmer but I've dabbled. One of the best sets of documentation out there is for Matlab - it's so. Damn. Good.
Part of what makes it good is that it's super modular, and very easily searchable, with excellent examples. Can't imagine trying to read it all start to finish would be useful - it's good because I can basically google "what built in function/library should I use for this?" And then search the matlab docs for whatever people recommend, and after a few minutes of reading I can get a MWE pulled together for my use case.
patternrelay@reddit
Yeah, that’s pretty normal honestly. Most docs work better as a reference while you’re building something, not as a cover to cover read. Tutorials teach the flow, docs are usually there for solving specific problems once you already have context.
mxldevs@reddit
It's useful to go over the entire docs because there's going to be tons of unfamiliar concepts and keywords if it's a field you're not particularly familiar with.
But a lot of docs just aren't great either.
carcigenicate@reddit
Ya, if I'm learning a new library, it's common for me to skim the entire docs just to get a feel for the structure, terminology, etc. I only tend to do that once, though, then I spot read as I need to learn about specific functions/classes.
dialsoapbox@reddit
I wasted so much time doing this.
Part of it was driven because of interviews, feeling not knowing enough, another part because i felt I needed to know a whole system/language/framework/ect before I can use it. Waste of time.
Read quick start guide first to get yourself familiar with the topics. Then you can go into the what is needed to use specific part of whatever you're using, then you can read up on the details/tweaks.
AdventurousLime309@reddit
Yeah, that’s actually how most developers use documentation. Docs are usually more like a reference manual than a textbook. You rarely read them front-to-back unless you’re learning the overall architecture or concepts for the first time.
The common workflow is:
have a problem → search docs for that specific thing → copy/adapt example → repeat enough times that the patterns start sticking naturally.
Tutorials teach flow. Documentation helps solve targeted problems. Over time you get better at navigating docs instead of “studying” them linearly.
victoria_suszek23@reddit
Both, depending on which part. Tutorials and Getting Started guides are meant to be read in order, API references are for lookups. What you're realizing is that you tried to read a reference like a tutorial, which is why it was slow, and now you're using it like a reference, which is fast. Your current approach is exactly the workflow most devs use, you just figured it out faster than I did.
gm310509@reddit
It depends upon the type of documentation. If it is a guide, then yes, read it from end to end (and follow along with it, trying out the examples as you go).
If it is reference information, then no, it is more like what you described where you need to do something so you look that thing up in the manual and just learn that part.
The first one is like a story you read along and follow the guide. The latter is like a dictionary where you look up what you need.
Then of course there is plenty of crappy documentation where it tries to be both, but succeeds at neither.
Hopefully that makes sense.
crawlpatterns@reddit
yeah thats pretty much how most people use docs honestly. i used to try reading them top to bottom too and would burn out fast, but they make way more sense once you already have a problem youre trying to solve. tutorials teach concepts in order, docs are more like a reference manual you jump around in. after awhile you kinda learn where things are and how to search for what you need instead of trying to memorize everything first
Ornery_Policy7718@reddit
Docs are reference material, not textbooks. The mental shift that changes everything : read the “getting started” section once to understand the mental model, then never read linearly again. After that, use docs like a dictionary — you go in with a specific question and come out with a specific answer. The exception : if a library has an “overview” or “concepts” page, that one is worth reading fully. It tells you what’s possible so you know what to search for later.
burlingk@reddit
Think of it as kind of a 'yes and' sort of thing, or a 'no but' sort of thing.
Documentation will often have a table of contents and section labels that you can jump around between easily. Skim them once, then go in depth on what you need.
Some people skip the skimming bit. Most do probably.
quietcodelife@reddit
two different modes: skim the overview once so you know what exists, then use it as a reference for the rest of your life. treating the API reference like a textbook is usually what causes the confusion.
blechnapp@reddit
both answers above are kinda right depending on which part of the docs you mean.
most docs split into three layers: getting started or tutorial (read linear once), conceptual overview (skim once, makes the rest click), and API reference (lookup only). if you treat the API reference like a textbook youll forget 90% of it. but if you skip the overview entirely you wont know what to search for, which is what Aqus10 is hinting at.
for arcade specifically: skim the conceptual sections once so you know Sprite, Scene, Camera, Window etc. exist as concepts. after that look up specifics only when you need them.
darkmemory@reddit
To add on, when doing a lookup for an API, it can be helpful to go up and down a layer or two, briefly looking at potential alternative routes to a solution through examining similar endpoints, or doing a bit of tracking of what resources are accepted and glancing at alternative functions that might make use of it. Sometimes a solution is adjacent to one's initial expectations. (I wanted to say it's best to use a blurred interrogation of the docs, or perhaps a less precise, wider perspective investigation.) Sometimes this will occur naturally when learning, but as it becomes more ingrained I've seen plenty of coworkers overlook something in the periphery and complain about being blocked.
blechnapp@reddit
yeah this is honestly an underrated habit. once you start poking at adjacent functions the mental map of a library builds up way faster, and you find the right tool the first time more often than not.
te5s3rakt@reddit
based on my vast experience reading documentation, I can say that documentation is assumed it won't be read.
every developer writes it because they were told too, not because they wanted to impart knowledge.
that's why so much of it is bad lol