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
