Re: [PATCH v2 0/4] Rewrite the top-level index.rst

[David Vernet]

On Fri, Sep 23, 2022 at 09:03:36AM -0600, Jonathan Corbet wrote:
> >> 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.
> >
> > I understand and yes, maybe it's the right thing to do; but OTOH that
> > page is a mess for quite a while already, so is it really a big problem
> > to just leave it like that for 9 or 10 more weeks while trying to bring
> > in a few more people that might be able to directly bring us on a good
> > long-term course?
> 
> 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...

Just to throw my hat in the ring here for the discussion -- I think we
need to bear 2 things in mind:

1. Reorganizing the front page for docs is probably something that's
disproportionately susceptible to bikeshedding. I don't think that's
happening in this specific discussion, but rather, I think we have to be
cognizant to not let ourselves drown in getting 100% consensus on
something like this given that it's likely to garner a lot of subjective
opinions.  I am not trying to straw-man Thorsten's point here because I
don't think he's claiming this isn't true, but rather just point out
that it might be better to land something now that's strictly an
improvement, and then worry about perfecting it later, precisely because
otherwise we'll probably just spend forever livelocking on it.

2. I think we can all agree that what we have now, i.e. listing every
single link on the front page, is really bad. Having hundreds of links
on the front page is actively worse than having just a few, because none
of them have any meaning anymore.  Given that the index is easy to see
and click on if anyone wants to go back to "show me all the links" mode,
my perspective is that we should just land this as is, and worry about
perfecting the layout / specifics later.

Thanks,
David