Received-SPF: pass (google.com: domain of linux-kernel+bounces-21039-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Message-ID: <01f5686d-2fcc-49e5-8e78-7b4048c8be7b@amd.com>
Date: Tue, 9 Jan 2024 09:21:49 -0600
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH 0/1] docs: Include simplified link titles in main page's
 index
Content-Language: en-US
To: Randy Dunlap <rdunlap@infradead.org>,
 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>
 <aa2ddfcc-8f2e-42c7-a81d-651a281eb6a3@infradead.org>
From: Carlos Bilbao <carlos.bilbao@amd.com>
In-Reply-To: <aa2ddfcc-8f2e-42c7-a81d-651a281eb6a3@infradead.org>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?utf-8?B?Tkd6ZFZDNnJ0bTdZTnJrcG1PaHBUUWpVOFhTTmpib29QNjRJbU1WTWZFVzF6?=
 =?utf-8?B?a2hhbTFQWlphaXJpZEdiamk0REVTUFZPbnVzNUZVOTlOZU9FMCtlWXY4QVdR?=
 =?utf-8?B?czlna3lqZ1hxUGxnU3VsSDVlR0RMMHBaTHo1ZDJFZmpIWFFaRkh2Z3RTVmpz?=
 =?utf-8?B?Skl3M1ZTWmtJM3c4NlZuUDRTcnVvMHdjeThtRmcrWHJDcVlhT0JybXlxbVY4?=
 =?utf-8?B?cXo3OXZFZ2NYMGUwQ0MvZkoyVnhtZ0VVbXZvM0ZkUVl4dS96UGdqY014aDNT?=
 =?utf-8?B?MHFlZWllK3ZXRSs2STRNaG01MEhPZXRtOW5USTRUVnZGcU5LWkpxL2dDZmkx?=
 =?utf-8?B?aFJ0RENFT0xibndQRUgyV012MGcvbEcxOTFRcUlkNVNvQ0pTN2xtQ1hRRjJQ?=
 =?utf-8?B?ZUFHcTZDTFBSNkkwNHp4UUY2eEVlNDVaR25ZQUNObDg2OGxUMTkyenlXejhn?=
 =?utf-8?B?L3M1bExBWUhmZlp5amhzeTNqM2Q2UnVDOXh5SDRzS3hzSUVYbnEzUzR6RWRG?=
 =?utf-8?B?WXBYamdXaVB6U1F5SCtpMWlpcVF4b01kSnlsN2MxSTJTWDRzdjZsSFMxT3Az?=
 =?utf-8?B?Q3o4enI3MllzZnhhQzFUYmdWZFZRdHNYSFhKQm5aaDRadnNtMUh5bDYzUzJz?=
 =?utf-8?B?YXJlOFBtV0xxNFlWSTl1TDRqMkFDTCtLRUJCREVHMGpzTmRhS1pIVkVJTmZa?=
 =?utf-8?B?Z0E1MzlvY3VoQmd3RXNnTDRkNHRwN3V2dGY2WFhqS1hGd0RlWVI5OEt1WGs1?=
 =?utf-8?B?eXoza0ZXcG9hU1F6V09kb1BTVStCeFZWY3hYbmZOQUxuNHZmQnRuTWt6bER6?=
 =?utf-8?B?dzFORGVaY0VtWFJjVzFCZ3NpZ2llQ0JaTXUzb3lnUEFVZXVNRWFOSGtmSkFH?=
 =?utf-8?B?L1BwUkFIalZKMWkyV2JEa2hBamh0OG10bXNyVDZtM3ZIZXNKanpFczZBcktv?=
 =?utf-8?B?ZGJHN3ZuakJYQzRXb0V5eE8xdFN2NURDQWdZR0NHMHQ2YjNSRkRLTndnOS95?=
 =?utf-8?B?MVBkSFJxS1hDYU5adDFLUnlSSlNhaXhtelRpU1NUWjZRa0tEUE1tOWtqMGFO?=
 =?utf-8?B?WnFUdUtJeDZsNmh1ODluVlFZQUxzRi84SnpKcVhoY3NlODh1Sk1sTWppaE9V?=
 =?utf-8?B?eEdaSTFyZFZ2MDNsSXczODhWVUgvZkhjQ3JnZ2pmcEpXWVZ5Tzg1YjRhd0NK?=
 =?utf-8?B?U1NVcnBlODF0QmVXYzdhVWlRRTg0NVlUanY4clo5VU5zUFBoZTBtOWdCYk42?=
 =?utf-8?B?S1pSR1YvalpuOFpLQ0l5YW9MUy85YjZoN0tMTUhYTC8rVDhZWkRoTlVZc1cr?=
 =?utf-8?B?WEhJd2duMk9JNHlrU3RaaFNVQitVSmt1RzBINFVqTmRaWCtMTTVNcXZtejlk?=
 =?utf-8?B?MTVsR2E4Ukx2MEJZZEhpVXlDVDhqRWZtZXMzTkI0cWcxUW9FU3BNOGZ2ZDZQ?=
 =?utf-8?B?eFNFUlhCZStMWDNROGZodWlwSUwrQmVXTUpwcFBwOE1zb09aWlFGdjh2WHBx?=
 =?utf-8?B?cm5xbXRKTXBWbWZJNGJIRGZuQmxxNFYycmlKUTliN0tad3FPZFAxRnMvd3J1?=
 =?utf-8?B?dGc5bXlyTXNkc2o4clFiVlUrdEU5YVlWTHBOUklKNDR1UnZPeC9LeEZUUnM2?=
 =?utf-8?B?VVRNM2R1NUREWWh5S1dFdXNYMmF1dVp3REVVT2VJcGloSVkwYzBsOXVmNytX?=
 =?utf-8?B?VVhwcHFWYXhaeGk4WTdHeEtHRnNQM0tRaTR5aHVDOTZlZHZXVE1rUmRzVzJV?=
 =?utf-8?B?VDdtOTVGWXp2bE84WHhQaVAxaUFaemM2K0U3WFk5MGVBNnVscUk1SmR4TFNp?=
 =?utf-8?B?R3MvWnJ2N1Y0THpDNFRFVEE4K0FsZ21LWFJ3MmRrMldDM2IrZGxoM2NPK2ZU?=
 =?utf-8?B?c0tBL0dMa29ZLzRpb3h4cmU1RVFzWjd6WUExdklBclBtMGEwMEt4a2VnN0xm?=
 =?utf-8?B?dW5lc25yRnVhaGwwU0htZGY3aS8yWDZkcXBWbU9GcHdtV2wrSlBVbDRJN1hr?=
 =?utf-8?B?dlhVWjduMzdkK01zN2NiQmxpZW5BU3lwQktLRlBxMTBpaUNYWkdoeGhYRmtQ?=
 =?utf-8?B?UXl0UTdXU2E0aWJGODJVWG9oZkc3ZTRTc01NT3hqbXRVYXFyM1AyT2VseVhv?=
 =?utf-8?Q?V2dC7gf09Sjc9WdtObPiGHQhi?=
X-OriginatorOrg: amd.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 233d7cec-bc7e-483f-08cc-08dc1126b4e3
X-MS-Exchange-CrossTenant-AuthSource: BL1PR12MB5874.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 Jan 2024 15:21:52.2651
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: A0MIqH9JJO25zJekT6udKxzLdqcDBMsDqrf2xsBV1eoPvJ50n349bLQ5MRXOc4Pdc+cwvAzfdP1gJe7AmumVBg==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN0PR12MB6002

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@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.

These are good suggestions, sending v2.

> 
> Thanks.

Thanks,
Carlos