The GNU C Library Manual - Authoritative or not?

[Carlos O'Donell]

On 5/22/20 6:30 AM, Michael Kerrisk via Libc-alpha wrote:
>>> I realize these are just omissions that could be fixed.  But until
>>> they are, the manual cannot very well be taken as authoritative.
>>
>> Less complete does not mean less accurate; rather the opposite, at
>> least in general. Unofficial documentation that documents specific
>> observed behaviors that are not officially documented contracts is
>> inherently *less accurate* because the information it's providing is
>> potentially subject to change.
> 
> The last few words there could be taken to sound like a version of "we
> didn't document a contract, therefore we can change the behavior".
> Repeated experience has shown that doesn't fly. When there is no
> documentation of the behavior, users one way or or another discover it
> for themselves and encode that understanding into their behavior and
> applications, thus forming an implicit contract which typically is
> hard to break. (I'm sure you know this; I think it's just worth
> emphasizing the point.)

Absolutely. Missing information makes it difficult to set expectations
with users. Incomplete authoritative sources may be less useful than 
complete non-authoritative sources depending on the question you're 
asking, but it makes them no less authoritative.

Michael, I also want to say that I am incredibly appreciative
of the work you do on the linux man pages, and I try to show that by
being a regular contributor. For example documenting the exacting
details of how the API changed over time, and exactly what each
version did, and which versions had bugs is amazing. That is something
I don't think we need to capture in the glibc manual, but I think the
linux man pages should do that, and our users expect that of the man
pages.

Please keep up the good work, and ask for me if you think I can be
helpful with a review.

-- 
Cheers,
Carlos.