Hacker News Reader

Comment by simonw | Hacker News Reader

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

View on HN

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

> 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

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

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.

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.

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.

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

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

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

Reply on news.ycombinator.com