Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Fri, 23 Sep 2022 10:45:41 -0700
From:   Kees Cook <keescook@chromium.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Thorsten Leemhuis <linux@leemhuis.info>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        Jani Nikula <jani.nikula@linux.intel.com>
Subject: Re: [PATCH v2 0/4] Rewrite the top-level index.rst
Message-ID: <202209230942.E199E35F@keescook>
References: <20220922204138.153146-1-corbet@lwn.net>
 <7f02143c-461f-268b-0f17-7fe20a7423d6@leemhuis.info>
 <875yhep5l1.fsf@meer.lwn.net>
 <aa35d204-3033-96f2-ed83-c5034067fe4b@leemhuis.info>
 <87r102nnef.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <87r102nnef.fsf@meer.lwn.net>
Precedence: bulk

On Fri, Sep 23, 2022 at 09:03:36AM -0600, Jonathan Corbet wrote:
> For better or for worse, our most prominent user-facing documentation is
> the man pages, which are not a part of the kernel repository.  (Hmm...it
> wouldn't hurt to add a link to them to the front page, if and when a
> site with current man pages exists again).

Oh, yes, good idea!

> I don't have that much invested in the current ordering, we can
> certainly change it - anytime we want.  Anybody else have an opinion on
> that topic?

I think you, as the recognized leader of the doc project, can
establish some guiding principles on this, providing a bit of top-down
order. e.g. adopt a specific "Linux kernel documentation project mission
statement / strategy" that takes a distinctly opinionated stand on
anything that has been debated. For example, a strawman, not meant
to block this series in any way:

	Our primary audience is kernel developers, especially new
	contributors. Our next priority is people who want to engage
	with the developer community, but may not strictly be kernel
	developers (e.g. testers, bug reporters, researchers, press,
	etc). Next is users of the kernel, especially for how to use
	various features or configurations.

	Topics are ordered from least complexity to greatest complexity,
	with ties solved alphabetically.

	Links to development conversations must use Lore URLs unless
	they are specifically not available.

	Links to external documentation is strongly encouraged. Any
	dead links will be removed if not updated within 6 months.

	The "htmldocs" build target is expected to build without
	warnings.

It could live in Documentation/doc-guide/contributing.rst, and be the
tie-break for anything that comes up. Obviously, it, too, could change.

> I guess my feelings are that (1) I've had enough promises to help with
> documentation over the years to learn not to count on such until said
> help actually materializes, and (2) demonstrating what we can do can, I
> hope, only inspire people who know more than me to show what we *really*
> can do...

Ship it! "Patches welcome", etc. :)

-- 
Kees Cook