Rob Landley <[email protected]> writes: > On 9/30/25 14:57, Arsen Arsenović wrote: >> Rob Landley <[email protected]> writes: >>> It wasn't "lucky". >> It was, it was obvious even in first edition Unix - I'll come back to >> that. > > So obvious that you need to point it out 50 years later?
I don't know what you mean to imply here, but I doubt I'm the first. >> When documetning, these more complex interfaces ought to be >> decomposed into logical units for obvious reasons. There are also >> overarching themes that aren't simply attached to a single (or >> handful) of bits of the interface. > > There's more than one way to explain almost anything. Okay? >> In the original Unix v1 programmers manual (or, at least, the copy I >> could find), the term "file descriptor" is used 30 times, and defined >> (poorly) twice. > > And nobody ever bothered writing down what "inode" meant so I had to > ask Dennis Ritchie. > > https://lkml.iu.edu/hypermail/linux/kernel/0207.2/1182.html > > The downside of documentation being written by people who already know > the material. "Beginner's mind" is hard to recapture after the > fact. (I say this as someone who's been trying for decades.) > >> To clarify, I don't mean to imply that an OS-level manual should teach >> the reader about basic networking concepts, but it is still useful to >> briefly recap said concepts in order to clarify possibly-ambiguous >> terminology and set up standards for your documentation. > > A tutorial and a reference are not the same thing. That's tech writing > 101. > > Half of teaching is figuring out what your audience already knows so > you can connect to their knowledge base and fill in gaps without > boring them to tears repeating what they already know. It's _hard_, > and no canned source will get it right for every individual. Okay? I'm not sure I understand what that has to do with the paragraph you're responding to. As said, 'man' pages don't have the ability to provide context *at all*, whichever context might be necessary. >> Also, in my opinion, it is obvious > > No comment. > > Rob -- Arsen Arsenović
signature.asc
Description: PGP signature
