3 ms·

>if someone actually reads the manual Uh, I thought everyone does. >I don't see how manuals can be useful in the real sense I'm...not sure how you can say th

>if someone actually reads the manual Uh, I thought everyone does. >I don't see how manuals can be useful in the real sense I'm...not sure how you can say this. Maybe you mean, reading a manual cover-to-cover. I don't think "RTFM" means that. Don't read the whole thing if it's boring! But I find once I'm well into using/learning some piece of software, and want to know everything, reading the entire manual is fascinating. Plus they vary in quality and readability. The python docs are extremely readable..aren't they? (especially if you have a high tolerance for Monty Python gags). Man pages mostly suck for learning software the first time, but are brilliant for refreshing the memory. Mostly, I google lists of the best books on a subject, and read as many of them as I can get my hands on. If I'm not enjoying one, I turn to another.

noir_lord 8y ago
The projects that clearly care about good thorough documentation are relatively rare but worth their weight in gold. One of my favourites is Symfony, their documentation is phenomenal (right up to the ability to generate a beautifully formatted ebook straight from the docs). https://symfony.com/doc/current/index.html#gsc.tab=0 https://symfony.com/doc/current/index.html#gsc.tab=0 The structure is inviting, nicely thought out, makes it easy to get into from multiple points and well written. Also I really appreciate they have a good "Best Practices" section, too many frameworks give you a lot of flexibility without any overarching "We suggest you structure it this way" which means that you can pick up two projects based on the 'same' framework and they bare little actual resemblance to each other. That matters when you inherit someones codebase/decisions.
JohnHaugeland 8y ago
> > >if someone actually reads the manual > Uh, I thought everyone does. ... have ... have you ever met another programmer?
- AnimalMuppet 8y ago
  The old ones did this. Want to learn C? Read K&R. Want to learn Perl? Read the Camel book. Want to learn C++? Read Stroustrup. That was the way we learned. These days? Not so much. Stroustrup is now big enough to use in self-defense. I'm not sure there ever was an equivalent book for Java. (There is one for Go, however.) React? Angular? TypeScript? Do they have authoritative books? If they do, is that the canonical way to learn them? I think something changed 20 years ago. The book used to be the way to learn, and now it's not. I don't know if the programmers changed, or if the languages changed, or if the books changed, but something did.
  - JeremyBanks 8y ago
    FWIW Rust has "The Rust Book" as their primary long-form documentation, separate from their reference documentation. It's a common starting point for people new to the language. I read it in chunks as I was getting started. I'm not sure how it compares to those works of the past (perhaps less detailed?), but I found it much more approachable than most languages' documentation and more in-depth than most languages' tutorials. The old ways may not be entirely lost.
    - steveklabnik 8y ago
      All three of the books your parent mentions were explicit influences on TRPL. So yes, it lives on :)
- yesenadam 8y ago
  Haha... well, in person, probably not. I've been programming since the 80s, and most of the 'voices' I've heard have been writers on programming, besides more recently online on here, SE etc. Not programming professionally, just doing whatever I wanted. I got a copy of Stroustrup 20 years ago, but never read most of it. Have a few other massive C++ books, and a few smaller ones, that I consulted constantly though. Recently I got into LaTeX, read almost every book on LaTeX + TeX available (a couple of dozen), all very good. Got into Prolog, (about a dozen books), all very good... All the books on AWK are great. Same with Lisp. Sure, Stack Exchange is a wonderful resource, hard to imagine doing without it. It's like having a teacher - read the books, then consult the teacher for questions that you can't immediately find answers for in the book. Some things are done better online: bash has a few great websites, and w3schools is great for css/js/html.
emmelaich 8y ago
> Uh, I thought everyone does. I thought no-one does! :-)

noir_lord 8y ago

The projects that clearly care about good thorough documentation are relatively rare but worth their weight in gold. One of my favourites is Symfony, their documentation is phenomenal (right up to the ability to generate a beautifully formatted ebook straight from the docs). https://symfony.com/doc/current/index.html#gsc.tab=0 https://symfony.com/doc/current/index.html#gsc.tab=0 The structure is inviting, nicely thought out, makes it easy to get into from multiple points and well written. Also I really appreciate they have a good "Best Practices" section, too many frameworks give you a lot of flexibility without any overarching "We suggest you structure it this way" which means that you can pick up two projects based on the 'same' framework and they bare little actual resemblance to each other. That matters when you inherit someones codebase/decisions.

JohnHaugeland 8y ago

> > >if someone actually reads the manual > Uh, I thought everyone does. ... have ... have you ever met another programmer?

AnimalMuppet 8y ago
The old ones did this. Want to learn C? Read K&R. Want to learn Perl? Read the Camel book. Want to learn C++? Read Stroustrup. That was the way we learned. These days? Not so much. Stroustrup is now big enough to use in self-defense. I'm not sure there ever was an equivalent book for Java. (There is one for Go, however.) React? Angular? TypeScript? Do they have authoritative books? If they do, is that the canonical way to learn them? I think something changed 20 years ago. The book used to be the way to learn, and now it's not. I don't know if the programmers changed, or if the languages changed, or if the books changed, but something did.
- JeremyBanks 8y ago
  FWIW Rust has "The Rust Book" as their primary long-form documentation, separate from their reference documentation. It's a common starting point for people new to the language. I read it in chunks as I was getting started. I'm not sure how it compares to those works of the past (perhaps less detailed?), but I found it much more approachable than most languages' documentation and more in-depth than most languages' tutorials. The old ways may not be entirely lost.
  - steveklabnik 8y ago
    All three of the books your parent mentions were explicit influences on TRPL. So yes, it lives on :)
yesenadam 8y ago
Haha... well, in person, probably not. I've been programming since the 80s, and most of the 'voices' I've heard have been writers on programming, besides more recently online on here, SE etc. Not programming professionally, just doing whatever I wanted. I got a copy of Stroustrup 20 years ago, but never read most of it. Have a few other massive C++ books, and a few smaller ones, that I consulted constantly though. Recently I got into LaTeX, read almost every book on LaTeX + TeX available (a couple of dozen), all very good. Got into Prolog, (about a dozen books), all very good... All the books on AWK are great. Same with Lisp. Sure, Stack Exchange is a wonderful resource, hard to imagine doing without it. It's like having a teacher - read the books, then consult the teacher for questions that you can't immediately find answers for in the book. Some things are done better online: bash has a few great websites, and w3schools is great for css/js/html.

emmelaich 8y ago

> Uh, I thought everyone does. I thought no-one does! :-)