3 ms·
I've been trying to develop the habit of reading the documentation from cover to cover of any tool that I've been using for more than a year or so. I find that
by simonw 4y ago
I've been trying to develop the habit of reading the documentation from cover to cover of any tool that I've been using for more than a year or so.
I find that reading all of the documentation for a tool you've just started using isn't as valuable: if you haven't gained any experience with it yet, a lot of what you read will fail to stick.
Once you have a few months (or years) of experience under your belt doing a thorough review of the documentation can massively increase your abilities with the tool.
Here are some notes I made when I finally spent the time to read through every page of the Jinja documentation for example: https://github.com/simonw/public-notes/issues/4 https://github.com/simonw/public-notes/issues/4
- StivDC 4y agoDefinitely second this. Plenty of times have I read documentation for a new library I'm about to use, only for when I get around to using it being right back on the documentation page looking at how to use it. Only after I've given it a whirl, tried some stuff out can I then look at documentation and have things stick.
- Aromasin 4y agoI still think there is value in reading it cover to cover though, if only for spaced repetition. I'll skim read it to know the titles/where to find everything, use the tools, read a bit deeper, user the tools some more; repeat. Iteratively checking the documentation is what makes it stick.
- armchairhacker 4y agoI use documentation a lot but reading from cover to cover? I usually look at the documentation while I'm writing the code, for the specific concepts and symbols I need to understand or am having issues with, and over time I learn more about the general framework. This also helps because the information is relevant so I remember it better. For example the Coq manual: https://coq.inria.fr/refman/ https://coq.inria.fr/refman/. The first time I looked at this it was extremely intimidating. It includes a lot of dense concepts (type theory) and forward references. There's no way I could read it through without forgetting 90% of it because I couldn't understand. As I've used Coq and kept going back to the definitions, I now understand its docs a lot better. Now I can actually read something from them, and I understand the grammar notation and terminology and forward references; and Coq's detailed, technical documentation is invaluable and essential for debugging the language's many quirks and edge cases. But it took hands-on experimenting with Coq to get to that point.
- Swizec 4y ago> I use documentation a lot but reading from cover to cover? Great way to build a reference index in your brain and to know what's possible. Very unlikely you'll think to look up the documentation for a feature/ability that's an unknown unknown. Reading cover to cover is a way to build known unknowns. Stuff you know exists, but don't know the details until you come to a use case and look into it. Which reminds me: I should go read more documentation cover to cover :D
- commandlinefan 4y ago> reading from cover to cover? I do, whenever it's possible and I can get away with it. Increasingly, online documentation is organized in a way that there's no really meaningful way to read "all of it" because it's not organized linearly. Back in the days when documentation actually _had_ literal covers, there was a clear order that you were supposed to read it in, and (at least some) care had been taken to ensure that concepts were defined before they used. Most online documentation seems to be written under the assumption that you already know what it's for and why it's useful, and you're just looking for how to accomplish some specific task. There are still physical printed books from publishers like O'Reilly (although their quality has gone way down) that do try to actually explain the what and the why along with the how, but I run into some sort of reverse snobbery when I try to dedicate time studying them: "why are you reading a _book_? Just search the online documentation or google it".
- waboremo 4y agoAgree with this analysis, when docs are written well, it's quite nice to read them through. They're succinct yet thoughtful. Most docs aren't like that though, they are either trying to do far too much (being a marketing page + docs + list of jargon + competitive analysis etc), or are so minimal they do as you say and are exclusively useful to those already very knowledgeable about it. I think docs organizers should plan it as if they were writing a short linear novel to improve those glaring issues. It would go a very long way to improving general readability even if you don't read them that way. Easier said than done of course, but there's value the "cover to cover" mentality.
- 4y ago
- toadi 4y agoI am getting old. But in the old days when you asked on IRC a question that could be answered by reading the manual you got the answer RTFM. Then there was stackoverflow where everyone got used asking questions and people obliged to answer even those. All just to get karma and/or badges. Personally I still prefer to run through documentation...