Thorsten Leemhuis <linux@xxxxxxxxxxxxx> writes: > On 22.09.22 22:41, 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. > > That's true, but is it maybe good or even important for googleability? > When you talked about this in your LPC talk this went on in the matrix chat: > > ``` > Nur Hussein > I feel like every existing page needs to be accessible (somehow) > from that starting page > > Zsuzsa Nagy > > access to all pages <- findability from a search engine (technical > author talking here) > > step #2 in-site search for those who already landed on your pages > ``` So every page remains accessible, just like they are now. They just aren't linked directly from the front page - as many pages already are not. I honestly don't understand what the problem is here. *No* site links everything directly on its front page. Even if it had an effect on search engines, I think it would be wrong to prioritize SEO over basic usability. >> 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/ > > I still think we're doing all this to build something for users and > hence docs for users should be at the top spot. I'd even think "those > people are selfish" if I'd look into the docs of a software and find > texts for developers at the top spot. Again ... who are the users? I maintain that the actual users of our docs are primarily kernel developers. >> Unless I get screams I plan to slip this into 6.1. It is definitely not >> the final form of the front page, but I doubt we'll ever get there; we can >> change it in whatever ways make sense. > > My 2 cent: why the rush? I'd say: let's try to get some feedback from > Zsuzsa and experts on docs first. I'd be willing to approach them. If > that doesn't work out over the next few weeks, just merge what you have > for 6.2. I want to do it because it's a clear step forward and has already been pending for a month. It is surely not perfect, and there will undoubtedly be changes, perhaps big ones, to come, but I cannot imagine a scenario where we want to go back to the mess we have now. Thanks, jon
