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