Rust-for-linux archive mirror
 help / color / mirror / Atom feed

From: Jonathan Corbet <corbet@lwn.net>
To: Carlos Bilbao <bilbao@vt.edu>, Miguel Ojeda <ojeda@kernel.org>
Cc: "Alex Gaynor" <alex.gaynor@gmail.com>,
	"Wedson Almeida Filho" <wedsonaf@gmail.com>,
	"Boqun Feng" <boqun.feng@gmail.com>,
	"Gary Guo" <gary@garyguo.net>,
	"Björn Roy Baron" <bjorn3_gh@protonmail.com>,
	"Benno Lossin" <benno.lossin@proton.me>,
	"Andreas Hindborg" <a.hindborg@samsung.com>,
	"Alice Ryhl" <aliceryhl@google.com>,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	rust-for-linux@vger.kernel.org, "Carlos Bilbao" <bilbao@vt.edu>
Subject: Re: [PATCH 0/1] docs: Include simplified link titles in main page's index
Date: Fri, 15 Dec 2023 08:47:01 -0700	[thread overview]
Message-ID: <87o7erqxhm.fsf@meer.lwn.net> (raw)
In-Reply-To: <20231211005442.95457-1-bilbao@vt.edu>

Carlos Bilbao <bilbao@vt.edu> writes:

> The general consensus is that the documentation's website main entry point
> and its sidebar leave room for improvement.
>
> Something we can easily fix is that there's too much duplicated text.
>
> To that point, consider the titles "The Linux kernel user's and
> administrator's guide" and "The Linux kernel user-space API guide." We get
> it, it's the Linux kernel. It's assumed that everything listed pertains to
> the Linux kernel, given the overarching title, "The Linux Kernel
> documentation." Constant repetition of "Linux" and "kernel" (45 times
> each), "documentation" (21 times), and "guide" (18 times) are excessive and
> affect UX.
>
> I propose simplifying without altering actual document titles, the text
> linking to these documents on the main page ("link titles"). For example,
> "The Linux kernel user's and administrator's guide" could become "User's
> and Administrator's Guide," and "A guide to the Kernel Development Process"
> could be "Development Process". This is what my patch does.

So I totally agree that the sidebar can use improvement, and I agree
that this patch makes it better.

I'm less convinced about the changes to the page itself, which I
consider to be somewhat more important.  There, I think, the more terse
titles are likely to be less useful for readers.  (OTOH, I think the
result is an improvement for those reading the RST files).

I spent some time a little while back understanding how the sidebar is
generated, and feel that we can make it into what we want it to be.  But
I don't think we've decided what we really want it to be.  I think there
is simply too much stuff there in general; it's never going to be
manageable that way.

There was a suggestion at the kernel-summit session to just put the
top-level books there:

	Kernel documentation
        Development-process guide
        Core API manual
        Driver API manual
        User-space API manual
        Maintainer guide
        Documentation guide

Then perhaps add one level for whichever book is open (if any) at the
time.

I'm sure there are other, better ideas as well.

Meanwhile, I'm pondering on this patch, would like to know what others
think.  Carlos nicely put up some comparison images for us:

  https://github.com/Zildj1an/linux-kernel-docs-compare/blob/main/comparison.png

...so it's not necessary to build the docs to see the results.

Thanks,

jon

next      parent reply	other threads:[~2023-12-15 15:47 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20231211005442.95457-1-bilbao@vt.edu>
2023-12-15 15:47 ` Jonathan Corbet [this message]
2023-12-18 15:57   ` [PATCH 0/1] docs: Include simplified link titles in main page's index Carlos Bilbao
2023-12-21  5:59   ` Vegard Nossum
2023-12-21  6:11     ` Randy Dunlap
2024-01-09 15:21       ` Carlos Bilbao

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87o7erqxhm.fsf@meer.lwn.net \
    --to=corbet@lwn.net \
    --cc=a.hindborg@samsung.com \
    --cc=alex.gaynor@gmail.com \
    --cc=aliceryhl@google.com \
    --cc=benno.lossin@proton.me \
    --cc=bilbao@vt.edu \
    --cc=bjorn3_gh@protonmail.com \
    --cc=boqun.feng@gmail.com \
    --cc=gary@garyguo.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=ojeda@kernel.org \
    --cc=rust-for-linux@vger.kernel.org \
    --cc=wedsonaf@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).