Re: Move GNU manual pages to the Linux man-pages project

["Arsen Arsenović" <arsen@aarsen.me>]

[-- Attachment #1: Type: text/plain, Size: 2177 bytes --]

Rob Landley <rob@landley.net> writes:

> On 9/30/25 14:57, Arsen Arsenović wrote:
>> Rob Landley <rob@landley.net> 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ć

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 381 bytes --]