Re: For review: memusage(1) man page

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Hello Alfred,

On 07/22/2014 10:39 AM, Alfred M. Szmidt wrote:
> Jan, are you willing to assign copyright for those documenation bits
> to the FSF? I'll happily convert them into texinfo.
> 
>    I must say that this is an odd position to take. While it would be
>    nice to have documentation in the glibc manual, the glibc
>    developers did not bother to add anything to the manual when
>    writing these interfaces, so it hardly seems like anyone else is
>    obligated to do so (assuming that person wanted to even jump the
>    CLA hurdle...).  In any case, man pages does (good) pages that
>    describe the libc interfaces (including commands).
> 
> Someone sends a useful patch for glibc, but glibc is not documented
> using man pages so the natural thing is to have it in a format that
> can be accepted into glibc.

My problem was with your earlier statement: "This, memusagestat, and
mtrace should rather be put into the glibc manual." Perhaps it is
just a language misstep, but "should" implies that the author is
in some sense obliged to send documentation patches to the glibc 
manual, rather than elsewhere (e.g., man pages). I don't agree. 
(But, I'll repeat what I said earlier that it would be good if the
doc is in the glibc manual, also.)

> What is odd is to dismiss such a contribution 

I did not dismiss any contribution (or I am misunderstanding your point).

> and start making excuses
> as to why one should not "bother" updating the offical, and canonical
> documentation for glibc.  

I'm not making excuses. But, I am suggesting that the CLA is a 
rather pointless hurdle. Yes, we can argue that one; I've already
made my position clear and public elsewhere [1].

And, I can't help but make the observation that man-pages provides
documentation of the glibc interfaces that is frequently more thorough,
complete, and up-to-date than the "official and canonical" glibc manual.
I leave others to speculate how that situation could come about.

> And accusing people because they "couldn't
> be bothered" is quite an unfriendly attidue.  We all have things to
> do, and only have so much time to try and do everything.

I did not "accuse" anyone of anything, but it seems clear that
there are many cases where documentation was considered unimportant.
And, I probably could have expressed myself a little better and 
more temperately; I was reacting a little to what I perceived
was your implication (as I describe above).
 
Mostly, I was expressing frustration with a too common developer
attitude that the job ends at coding. For, without documentation
(i.e., a formal or informal spec), how can one tell where the
developer's implementation differs from their intention (i.e., a bug)?
Personally speaking, I've never considered a development project
complete if I did not also provide (extensive) documentation.

Cheers,

Michael

https://lwn.net/Articles/529522/

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/