On 02.09.22 01:16, Jonathan Corbet wrote: > The top-level index.rst file is the entry point for the kernel's > documentation, especially for readers of the HTML output. It is currently > a mess containing everything we thought to throw in there. Firefox says it > would require 26 pages of paper to print it. That is not a user-friendly > introduction. < > This series aims to improve our documentation entry point with a focus on > rewriting index.rst. The result is, IMO, simpler and more approachable. > For anybody who wants to see the rendered results without building the > docs, have a look at: > > https://static.lwn.net/kerneldoc/ > [...] Great initiative. But looking at the rendered result made me wonder: what overall structure for the docs are you aiming for in the end? I'm sure you have a picture in your head, but I failed to grasp it, as for me a few things looked a little odd: * we do all of this for the users, so shouldn't the section aimed at users be at the top? And list more things they will look for? * What is so important about "Architecture-agnostic documentation" and "Architecture-specific documentation" (both with just one entry) that they have to be listed here? Same for "Firmware-related documentation". And is the User-oriented section really the right place for the kbuild stuff, as from a quite look it seems most of those aim at developers and not at users? * Quite a few things I'd had expected on that front page aren't listed there. Sure, everybody has different expectations on what's important, but I for example hat expected "command-line parameters" or "Reporting issues" (here I'm obviously biased) to be somewhere on that page. This made me think: should that main index page maybe just have these three sections (apart from Translations) ? * User-oriented documentation * Application-developer documentation * Other documentation on the Linux kernel and its development I'd say that makes it quite clear where readers need to go from there, even if the name of the third section is a bit vague (but in contrast it becomes clear I'd say). Each section could list its five to ten most important documents before linking to a separate index file with more. And that index file for will need subcategories, too, otherwise it will become large, too. And sure, quite a few documents will be hard to categorize currently. Making things fit properly might take a decade or two (unless somebody hires a few people to bring order into this). But it would set a clear direction. It also would tell doc writers what tone and detail level to use when writing their texts, as that depends on the audience which becomes clearer this way. Ciao, Thorsten P.S.: /me wonders if Jonathan posted this patch-set as a bait and will force everyone replying to come to his LPC/kernel summit session "What kernel documentation could be" /me despite this replied, as he had planned to go anyway
