5 ms·

Old documentation was based on the didactic principle of presenting the foundation before jumping into the specifics. Online documentation seems to forget that

• jvanderbot 5y ago
  The best datasheets do this too. However, I'm getting quite tired of skipping the section about I2C every time. I get it, there's logical highs and logical lows and those need to happen with certain timing constraints. Still, there those pictures are, every time.
  • danachow 5y ago
    Lol, guilty - years ago I wrote a hardware manual / datasheet for a device with I2C interface. And I wrote yet another thorough I2C protocol section - and if I recall, nobody in the documentation department specifically asked for it - but all the similar datasheets did it so why not us - probably explains a lot. Did the timing diagrams in xfig.
  • throwanem 5y ago
    Yeah, but it's easy to skip once you know what it is and that you understand it already. For someone who doesn't, having it present may be vital. In my opinion, the same is true of computing - as a mentor, especially when working with folks who don't come to programming from a "typical" background, there's a lot of basic context that has to be conveyed precisely because so much of our docs assume they can leave out all the stuff that "everybody knows".
    • rhn_mk1 5y ago
      The worst is where you assume a vanilla implementation of some basic functionality, so you skip the explanation, but actually, there's a quirk inside that you only discover after scratching your head for a while. Newbies are lucky in this way, that they don't have even a mistaken reason to skip reading the basics.
    • StillLrning123 5y ago
      Unix/ Linux man pages are really hard to understand because of this
      • throwanem 5y ago
        True, but they make up for it by being also very difficult to use in their intended role as aides-memoire, both because of the way they're written and because the relatively primitive format provides no aid to search or navigation.
        • jvanderbot 5y ago
          I find `man X | grep Y` actually works OK, and the "see also" at the bottom is quite helpful for finding related information. But if I don't already know exactly what I'm looking for, it's hard to use. It's really difficult to "learn about" how to open sockets if I can't remember sockaddr_t exact spelling or the right header to include.
        • gnubison 5y ago
          On a BSD, try ‘man -Otag=l ls’ or ‘:tl’ (from less) for e.g. ls -l. This also works for larger man pages: ‘man -Otag=OCRNL termios’. More specifically, this requires the mandoc man implementation, which is also available on Linux — it’s what I prefer for all my machines. tl;dr: it’s groff(1), not the -man and -mdoc formats, which is primitive (in this sense).
  • dfox 5y ago
    I2C is one thing, Dallas datasheets that completely document the relevant subset of the 1wire state machine are another beast… On the other hand in the last month I have seen 40 page datasheets from Phillips/NXP/Nexperia that contain highlevel description of what the thing is supposed to do, ridiculously detailed description of I2C and reference to some kind of SDK that you should use to actually interface with the thing…
• iib 5y ago
  I read a comment once (that it will be impossible for me to find again), that suggested that this is actually a baked in assumption and it depends on the audience. Audiences in Europe were more likely to find it useful to be presented with the working theory first, and examples later, as a specialization of the theory. American audiences tended to prefer working examples first, and then a generalization to form a theory.
• gombosg 5y ago
  I often find this for some libraries. Like the new library Foo.js "inspired by Bar and Baz, but better", where the documentation is made up of, say, two simple examples and that's it. Fortunately, often this is not the case and documentation is very well written.
• userbinator 5y ago
  It also assumes people are smart and willing to learn and understand things, rather than stupid and needing to be herded to the answer.
• IgorPartola 5y ago
  Yes because before I can heat up my pizza leftovers I need to understand the theoretic underpinnings of electromagnetism :)
  • tehjoker 5y ago
    If your pizza is totally frozen or served on a metal plate, you might want to know why it either is working very slowly or is blowing up the house. :)
  • alar44 5y ago
    The only reason you know not to put metal in the microwave is exactly because of 60 years of manuals. It's common knowledge now. You bet they talked about radiation and how a magnetron works in a microwave back the 60s.
    • lovehashbrowns 5y ago
      Some of the 60 years worth of manuals get forgotten along the way. That's why you'll sometimes run into people who think you can protect your food from radiation by covering the food with a paper or plastic cover. Or people who avoid microwaves because of radiation poisoning. Maybe there's like a compromise where every X number of years, a product will come with a hefty manual which doesn't assume knowledge and starts at the basics as a refresher of sorts. Cell phones, microwaves, light bulbs, plastic containers. Actually, what I want more than anything to ship with thick manuals is skincare products. I have these more high end skincare products that came as a set and, let's be honest it was likely a waste of money. But I got it for the "experience," y'know? Anyway, none of the products tell me how to use them. They don't tell me what order to use them in. They don't tell me how often to use them. These are all things that you know if you're a girl and you don't know if you're a guy because, like you said, there are years worth of manuals--I just skipped those "lectures."
      • alar44 5y ago
        Do people think covering with paper or plastic helps block radiation? Pretty sure people so this to keep the microwave clean...