3 ms·

> 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

> 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.

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.