4 ms·

I 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 symbol

I 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 3y 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 3y 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 3y ago
  Agree 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.
- toadi 3y ago
  In the Oreilly days if you wanted to learn about a language there were 3 options. 1/ Learn the language with exercises - Fun book but you only use it once 2/ The definitive reference guide - that was the book I had on my desk with post its in. 3/ The cookbook - solving real world problems with examples Mostly I got the 2nd and 3rd options and didn't bother with the 1st. I think this concept was the best. Even for example command line tools. I read it once but I re-read it occasionally. You forget what is possible with the tool when first learning it. The next rounds will create a-ha moments and you pick new stuff up.
narag 3y ago
I use documentation a lot but reading from cover to cover? Impractical for everything but if some tool is your bread and butter, it's a good idea. I read the whole TurboPascal and Delphi manuals, the former in college, the later when I bought the first version as soon as it was released. Best time investment ever, for me. It helped that they were very well written. Later, pressing F1 you had a summary and useful sample programs that you could cut and paste into the IDE. But having read the manuals from cover to cover gave me another insight: knowing what was possible. When I joined online forums to get additional help, I found myself answering instead.

Swizec 3y 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 3y 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 3y ago
Agree 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.
toadi 3y ago
In the Oreilly days if you wanted to learn about a language there were 3 options. 1/ Learn the language with exercises - Fun book but you only use it once 2/ The definitive reference guide - that was the book I had on my desk with post its in. 3/ The cookbook - solving real world problems with examples Mostly I got the 2nd and 3rd options and didn't bother with the 1st. I think this concept was the best. Even for example command line tools. I read it once but I re-read it occasionally. You forget what is possible with the tool when first learning it. The next rounds will create a-ha moments and you pick new stuff up.

narag 3y ago

I use documentation a lot but reading from cover to cover? Impractical for everything but if some tool is your bread and butter, it's a good idea. I read the whole TurboPascal and Delphi manuals, the former in college, the later when I bought the first version as soon as it was released. Best time investment ever, for me. It helped that they were very well written. Later, pressing F1 you had a summary and useful sample programs that you could cut and paste into the IDE. But having read the manuals from cover to cover gave me another insight: knowing what was possible. When I joined online forums to get additional help, I found myself answering instead.