linux-kernel - Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <b55dc12b-0cd3-4f56-803e-4b26f1117c91@oracle.com>
Date: Thu, 21 Dec 2023 06:59:20 +0100
From: Vegard Nossum <vegard.nossum@...cle.com>
To: Jonathan Corbet <corbet@....net>, Carlos Bilbao <bilbao@...edu>,
        Miguel Ojeda <ojeda@...nel.org>
Cc: Alex Gaynor <alex.gaynor@...il.com>,
        Wedson Almeida Filho <wedsonaf@...il.com>,
        Boqun Feng
 <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>,
        Björn Roy Baron <bjorn3_gh@...tonmail.com>,
        Benno Lossin <benno.lossin@...ton.me>,
        Andreas Hindborg <a.hindborg@...sung.com>,
        Alice Ryhl
 <aliceryhl@...gle.com>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org
Subject: Re: [PATCH 0/1] docs: Include simplified link titles in main page's
 index

On 15/12/2023 16:47, Jonathan Corbet wrote:
> Carlos Bilbao <bilbao@...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