From: Vegard Nossum <vegard.nossum@oracle.com>
To: Jonathan Corbet <corbet@lwn.net>, 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
Subject: Re: [PATCH 0/1] docs: Include simplified link titles in main page's index
Date: Thu, 21 Dec 2023 06:59:20 +0100 [thread overview]
Message-ID: <b55dc12b-0cd3-4f56-803e-4b26f1117c91@oracle.com> (raw)
In-Reply-To: <87o7erqxhm.fsf@meer.lwn.net>
On 15/12/2023 16:47, Jonathan Corbet wrote:
> 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.
[...]
> 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
FWIW, I like it, but I would suggest these changes:
Driver implementation API -> Driver APIs
Testing -> Testing guide
Hacking -> Hacking guides
User-space tools -> Userspace tools
User-space API -> Userspace APIs
CPU Architectures -> CPU architectures
I know "user space" is technically two words, but the one-word form is
MUCH more prevalent in the kernel, for example if you check the mainline
log you'll see something like:
$ git log --grep 'user.*space' | grep -o 'user.*space' | sort | uniq -c
| sort -g | tail -n 3
3135 user-space
7835 user space
26917 userspace
I think it makes sense to pluralize API -> APIs in most places, so e.g.
"Core APIs", "Driver APIs", "Userspace APIs". Just to emphasize that
these are really collections of disparate APIs (e.g. workqueues is one
API, linked lists is another, etc.).
Vegard
next prev parent reply other threads:[~2023-12-21 5:59 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 ` [PATCH 0/1] docs: Include simplified link titles in main page's index Jonathan Corbet
2023-12-18 15:57 ` Carlos Bilbao
2023-12-21 5:59 ` Vegard Nossum [this message]
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=b55dc12b-0cd3-4f56-803e-4b26f1117c91@oracle.com \
--to=vegard.nossum@oracle.com \
--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=corbet@lwn.net \
--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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).