Why you should still read the docs
death.andgravity.com
death.andgravity.com
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
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.
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
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".
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.
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.
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.
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...
Being the one person who read the docs is the difference between being considered just another tech worker, and the "genius" people rely on for answers. It makes you invaluable, boosts your career, and leads to better outcomes.
Oh, this is so true.
I'm a compulsive doc reader (I even read the "user manuals" that come with toasters and such), and sometimes my friends tease me about it.
But I'm also the guy who knows the "magic incantations" and "secret features" that everyone thinks is an exceptional ability. But the "exceptional ability" is nothing more than reading.
This is one of the reasons I can't see much value in ChatGPT. Anything it gives me will be at most as accurate as the docs. Most of the time I either know what I'm searching for or I can glance at the TOC.
Docs are a lot more concise than general writing. I don't like having to read paragraphs and redundant explanations, the docs include types and small code examples which are easier for me to understand.
The docs are especially good whenever I have to deal with tricky edge cases and precise semantics, because most of the time the developers know these are tricky so they document them well (like I said, I'm fortunate to have good documentation).
ChatGPT is actually amazing for skimming. You can copy a large, rambling section of docs into it and ask for, say, a "three sentence summary" or "bullet points" and it will do an excellent job.
I specify "already know', because sometimes it gets irrelevant/useless information from low quality blogs or stackoverflow. That said, so does Google.
Plus, reading manuals is a skillset all of its own. It might seem easy to you, but so is reading novels - but you couldn't do that right at birth. Some junior devs just haven't developed that skillset.
The idea that someone is able to read yet can not read technical manuals while being in the CS space is just shy of unthinkable to me. Reading them slowly, I completely understand. Everyone reads technical writing slowly, since it requires a lot of thinking.
But that thinking is related directly to our day jobs. That thinking shouldn't be so foreign that it prevents people from reading technical docs, well written or poorly written.
Personal bias, perhaps, but still a very foreign concept.
Is it, though? The world-at-large since time immemorial has trended towards shorter attention spans and shorter bits of literature, less reading.
I would even posit most people hate reading with the fury of a thousand suns. RTFM isn't a stereotype for no reason.
Within our profession, which is almost entirely text based, yes. Outside of our profession, I'm happy to concede that literacy levels are demonstrably lower.
> I would even posit most people hate reading
It's part of our job, hate it or love it.
Worker A: Pushed the feature in 2 hours.
Worker B: Pushed the feature in 4 hours says he read the documentation.
This can be be a signal that Worker B is more mature/senior and takes the time to do it well, but it can also just be that Worker A is better (and also read the documentation), was familiar with framework X already or another reason that has nothing to do with "not reading documentation".
In that context the optimal manager behaviour is to do nothing, if Worker A was doing lower quality work it might show up at some point or Worker B might get more accustomed to framework X and do the tasks in 2 hours too.
Which is all to say, you can't as a manager have that level of insight without personally looking at the work output and being familiar with framework X, which I'd argue might be within reach of a team lead for a somewhat reasonably scoped product, but will rarely be the case in practice.
I had sort of a horrifying revelatory experience at a Java User's Group a few years ago (back when I erroneously thought that attending Java User's Groups was worthwhile). This was when Hadoop was fairly new, and the speaker was talking about some of the challenges that his group ran into getting it up and running. At some point, a woman interrupted him and said "but when you had an error, why didn't you just google the error message and find the solution?" He was admirably patient with her when he explained that in most cases, there was no error _message_, but actual incorrect behavior (or just nothing at all), but she kept arguing with him as though he was missing something obvious and important. Here was somebody with enough software experience to be attending a Java User's Group who had never encountered (or more likely had just ignored) a problem that a google message search couldn't fix.
After implementing the feature (using all kinds of CPython/pytest internals and hacks), the guy read the docs and said: "Yeah! We should absolutely rewrite this the right way!"
Never happened...
I find myself anticipating the day when new generations of developers may work almost exclusively with AI suggestions, rarely consulting updated documentation. The prospect of emerging as the seasoned developer with a trove of 'arcane' knowledge - simply gleaned from routinely perusing updated documents - is an amusing one.
However, this prediction doesn't factor in the potential of AI assistants being connected to the internet with a level of cognition sufficient to provide up-to-date suggestions, but a man can dream.
Hire a technical writer, it will pay off.
Companies seem more eager to hire for developer advocates than technical writers these days
I would say it has been very valuable in my recent learning adventure. It saved me a from numerous gotchas that would have bit me. It also gave me a base knowledge to know what to look for when I needed it.
Otherwise, I would have been Googling and shoveling crap together myself instead of doing things how they were intended.
* Write both reference doco and guide/tutorial doco. People need both kinds. They should cross reference one another, too.
* Indeed, all of the Five Ws And An H are important. Provide rationales/backgrounders, histories, and even bibliographies where appropriate, too.
* Think about your writing order. Try to make both reference doco and guide doco flow. People do not solely access them piecemeal randomly.
* Read what you have written.
* Remember that doco is for people who don't know stuff. It's not the responsibility of the users to find out, or outright guess at, what your stuff does and then contribute third party doco.
There are lots of other tips for good writing, of course, but these are the ones that seem of particular relevance here.
When docs are hard to navigate, read, and comprehend, then it's a red flag.
I never managed to use those manuals because I entered the field too late, but I wish the tools I use now have paper docs.