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] [day] [month] [year] [list]

Message-ID: <01f5686d-2fcc-49e5-8e78-7b4048c8be7b@amd.com>
Date: Tue, 9 Jan 2024 09:21:49 -0600
From: Carlos Bilbao <carlos.bilbao@....com>
To: Randy Dunlap <rdunlap@...radead.org>,
 Vegard Nossum <vegard.nossum@...cle.com>, 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 12/21/23 00:11, Randy Dunlap wrote:
> 
> 
> On 12/20/23 21:59, Vegard Nossum wrote:
>> 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.).
> 
> +1 for all suggestions.

These are good suggestions, sending v2.

> 
> Thanks.

Thanks,
Carlos