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?
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.
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.
Also, in my opinion, it is obvious
No comment.
Rob
