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.

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.

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

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.

Unix/ Linux man pages are really hard to understand because of this

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.

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.

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

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…

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.

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.

It also assumes people are smart and willing to learn and understand things, rather than stupid and needing to be herded to the answer.

Yes because before I can heat up my pizza leftovers I need to understand the theoretic underpinnings of electromagnetism :)

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. :)

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.

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

Do people think covering with paper or plastic helps block radiation? Pretty sure people so this to keep the microwave clean...

Yeah it's often for keeping the microwave clean but my mom is an example of someone that thinks it also blocks radiation.

It's not as common as other microwave myths but it's a thing.

“Don’t put metal into the microwave” requires neither a thick manual nor theoretical underpinnings of electromagnetism. It requires a warning sticker.

Incidentally, there are types of metal dishes that can go into the microwave and yet most people today don’t know that, probably because nobody actually read the manuals, just the warning stickers.

I am by no means against understanding the theory behind what you are doing. My degree is in physics for a reason. But the “older is better” adage is tiring. I guarantee you that most people didn’t read the 200 page manual for their microwave oven and neither would most people today.