Rob Landley [off-list ref] writes:

On 9/30/25 14:57, Arsen Arsenović wrote:

quoted

Rob Landley [off-list ref] writes:

quoted

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.

quoted

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?

quoted

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

quoted

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.

quoted

Also, in my opinion, it is obvious

No comment.

Rob

-- 
Arsen Arsenović