[HN Gopher] Why you should still read the docs
___________________________________________________________________
Why you should still read the docs
Author : genericlemon24
Score : 58 points
Date : 2023-05-16 12:06 UTC (10 hours ago)
(HTM) web link (death.andgravity.com)
(TXT) w3m dump (death.andgravity.com)
| aigoochamna wrote:
| I recently got back into the habit of reading documentation from
| cover to cover.
|
| 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.
| JdeBP wrote:
| The thing to learn from this from the opposite side of the fence,
| i.e. of a developer producing said libraries, is to write good
| doco:
|
| * 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.
| noam_k wrote:
| I once worked on project that needed a DSL implemented over
| pytest to let developers access a db ergonomically. I told the
| guy working on it that pytest has an advanced hook system, and he
| should read the docs.
|
| 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...
| simonw wrote:
| 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
| StivDC wrote:
| 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.
| Aromasin wrote:
| 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.
| armchairhacker wrote:
| 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.
| commandlinefan wrote:
| > 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 wrote:
| 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.
| Swizec wrote:
| > 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
| narag wrote:
| _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.
| 1ark wrote:
| Read the whole /prompt_toolkit/ manual today. It was great. Then
| I started coding. It should always be like that. Great docs.
|
| When docs are hard to navigate, read, and comprehend, then it's a
| red flag.
| ThalesX wrote:
| In my experience with AI-assisted programming, I've discovered
| numerous edge cases where the AI's suggestions are either
| outdated or flat out incorrect.
|
| 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.
| deofoo wrote:
| True, but it really depends on the documents. Unfortunately,
| technical writers are not being paid adequately, so this
| profession is not well developed. It is a highly complex job that
| requires a great deal of empathy and a thorough understanding of
| the product, in addition to excellent writing skills.
|
| Hire a technical writer, it will pay off.
| charlie0 wrote:
| I agree. Most orgs will say they want more/better
| documentation, but their actions (or lack thereof) shows the
| opposite.
| hardwaresofton wrote:
| Where do people look for/find technical writers these days?
|
| Companies seem more eager to hire for developer advocates than
| technical writers these days
| markus_zhang wrote:
| On a side note. I'm drooling over documentations in actual,
| physical paper, such as the ones for Microsoft C++, or older
| Linux, or Oracle database.
|
| 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.
| RealityVoid wrote:
| I like the idea, but when I am searching for something in the
| documentation, paper docs are much slower than Ctrl+F not to
| mention that it's right there on the screen. If there is any
| reference I need on hand constantly, I just print that.
| markus_zhang wrote:
| Yeah I agree. And I'm pretty sure online ones are more
| useful. But it's just the concept of something as heavy as a
| brick that intrigues me. Maybe I can take all those online
| docs and print as a pdf and then into paper.
| throwawaaarrgh wrote:
| Often people complaining about Technology X simply haven't read
| the docs. They're not always written, not always easy to find,
| and not always complete, but whatever _is_ there, is there for a
| reason: it 's something the developer thought you ought to know.
|
| 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.
| JohnFen wrote:
| > Being the one person who read the docs is the difference
| between being considered just another tech worker, and the
| "genius"
|
| 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.
| lakomen wrote:
| Why you should ... Useless, opinionated posts. If you need to,
| you do otherwise you don't. Why make a post about it other than
| creating content for advertising. Never understood those kind of
| posts. I don't need a post telling me that I should read the docs
| or do whatever else. I can come to a conclusion myself. This is
| just worthless junk.
|
| Why you should mow your lawn. Or shouldn't, or whatever. Stop
| telling me what to do, when you don't have the slightest
| information about my situation. Generic, opinionated, useless.
|
| Hell, generic is even in the guy's username. QED.
| gipp wrote:
| Learning from other perspectives besides your own is a pretty
| critical skill for anything in life.
| kettunen wrote:
| Wait... Did we stop reading docs at some point?
| switch007 wrote:
| Totally agree. I can't recall the amount of hours I've lost from
| thinking that I didn't need to read the docs. You see a huge TOC
| and think "oh I'm not going to use 90% of that" but often it's
| not the case.
| JohnFen wrote:
| But even in those situations where that _is_ the case, at least
| browsing the docs is useful. That way, you know what they
| discuss and where those things are discussed, so that when you
| hit one of the 10% items, you know where to look to learn more.
| globular-toast wrote:
| I'm forever telling junior devs to read the docs. All they seem
| to want to do is take other code and modify it slightly. I don't
| understand why reading is so difficult. Especially when the docs
| are great like Click and the others listed here.
| taubek wrote:
| Path of least resistance. Copy/paste from Stack overflow and it
| is done.
| manicennui wrote:
| It is not actually normal to use SO several times every
| single day to find code you can use, and it is not actually
| faster than knowing what you are doing.
| JohnFen wrote:
| Not only isn't it normal, but if a dev is doing that, it's
| a big red flag that the dev might be out of their depth.
| vlunkr wrote:
| Because they're in the mode of getting things done. They're out
| to prove themselves, they don't want to report to their manager
| that they haven't finished that feature because they're reading
| the docs.
| falcolas wrote:
| I vote that this is a failure of the manager to set and
| reinforce expectations.
| belval wrote:
| Counter-argument: an hypothetical manager simply won't (and
| very often can't) get involved to a point where they can
| fix this situation.
|
| 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.
| pavel_lishin wrote:
| Not all docs are written well.
|
| 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.
| manicennui wrote:
| Maybe they should find another profession? I don't understand
| this argument at all.
| pavel_lishin wrote:
| Junior developers are _junior_. There are many skills they
| don 't have. Being able to parse writing in a certain style
| is one of those skills. Should they find another profession
| if they don't instantly know how to rebase things in git,
| or how to track down a bug?
| globular-toast wrote:
| Yeah, thankfully we don't often get babies applying for
| positions.
| falcolas wrote:
| Reading, however, is a skill taught to all schoolchildren,
| and taken further in college.
|
| 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.
| Dalewyn wrote:
| >Reading, however, is a skill taught to all schoolchildren,
| and taken further in college.
|
| 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.
| falcolas wrote:
| > Is it, though?
|
| 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.
| commandlinefan wrote:
| > take other code and modify it slightly
|
| 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.
| armchairhacker wrote:
| I read the docs all the time. Fortunately I tend to use libraries
| with very good documentation.
|
| 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).
| ericbarrett wrote:
| > 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.
|
| 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.
| nkjnlknlk wrote:
| I read really fast. For tools I already know Phind has been
| really good.
|
| I specify "already know', because sometimes it gets
| irrelevant/useless information from low quality blogs or
| stackoverflow. That said, so does Google.
___________________________________________________________________
(page generated 2023-05-16 23:02 UTC)