How would we make linux man pages authoritative?

[Carlos O'Donell]

Michael,

Could we create a process by which we might incrementally mark linux
man pages as authoritative for a given C library implementation and
at the same time encourage more C library community involvement in the
development and maintenance of the linux man pages?

I'm including Rich Felker the main musl developer, because I think
this topic applies to musl, and the linux man pages already contain
some markup for other C libraries.

Let me paint a picture of the future (what else are Fridays for):

* The project manual is a task-oriented document that describes how
  to use APIs together to achieve certain purposes. We update the
  manual based on new uses and complex task-oriented requirements
  e.g. how do you effectively use clone, or vfork, or unshare with
  all the right APIs to do something useful like starting your own
  container by hand.

* The linux man pages are the authoritative reference for all the
  APIs that are derived from ISO C, POSIX, BSD, and other systems.
  I say "derived" because we do not follow them strictly, but instead
  derive from them and deviate where appropriate given the underlying
  kernel.

* A process exists to mark a manual page as authoritative for the C
  library API it implements e.g. Authoritative for glibc, or musl,
  or uclibc. Such markup means a developer from that project should
  review patches to that page in a timely fashion to agree that we
  haven't crossed any implementation boundary e.g. documented something
  that is not guaranteed. Such review needs a timeout as part of the
  agreement.

* The C libraries have as a goal to update the API documentation in
  the linux man page as the authoritative source of the API reference
  and make it part of their submission process. Yes, this involves
  committing across two projects, and some good coordination.

In such a future we have the following assurances:

* More developers familiar with C library implementations working on
  the linux man pages project, and providing continuity of care for
  the project.

* The linux man pages project accepts certain authors as needing
  to review, in a timely fashion, certain changes to certain marked
  man pages.

* The downstream C library implementations are all incentivized
  to contribute to the existing linux man pages project and support
  that effort, thus growing the quality and coverage of the man pages.

* We reduce duplication of efforts in documenting the APIs as they
  are derived, with differences, from ISO C, POSIX, BSD etc, for Linux.

The glibc project retains a manual as a task-oriented guide which
can be read by developers to learn how to do certain tasks, but does
not contain API references (those are delegated to the linux man pages
project). We incrementally remove the API references in the glibc manual,
and convert them one-by-one into task-oriented documentation about how to
use that API well.

I'm trying to think of a beautiful future. If you think this future
is ugly, please tell me so, and suggest something else :-)

-- 
Cheers,
Carlos.

P.S. Martin, please forgive me is this is the beautiful future you wanted.