Received-SPF: pass (google.com: domain of linux-kernel+bounces-7883-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
Message-ID: <aa2ddfcc-8f2e-42c7-a81d-651a281eb6a3@infradead.org>
Date: Wed, 20 Dec 2023 22:11:58 -0800
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH 0/1] docs: Include simplified link titles in main page's
 index
Content-Language: en-US
To: Vegard Nossum <vegard.nossum@oracle.com>, 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>,
 =?UTF-8?Q?Bj=C3=B6rn_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
References: <20231211005442.95457-1-bilbao@vt.edu>
 <87o7erqxhm.fsf@meer.lwn.net>
 <b55dc12b-0cd3-4f56-803e-4b26f1117c91@oracle.com>
From: Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <b55dc12b-0cd3-4f56-803e-4b26f1117c91@oracle.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit


On 12/20/23 21:59, Vegard Nossum wrote:
> 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.).

+1 for all suggestions.

Thanks.
-- 
#Randy