Received-SPF: pass (google.com: domain of linux-kernel+bounces-75437-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Message-ID: <6314de0b-a69c-4e72-9538-8b133fc50047@amd.com>
Date: Wed, 21 Feb 2024 13:58:35 -0600
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH v2 0/2] docs: Include simplified link titles in main index
Content-Language: en-US
To: corbet@lwn.net, rdunlap@infradead.org, vegard.nossum@oracle.com
Cc: bilbao@vt.edu, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
References: <20240109155643.3489369-1-carlos.bilbao@amd.com>
From: Carlos Bilbao <carlos.bilbao@amd.com>
In-Reply-To: <20240109155643.3489369-1-carlos.bilbao@amd.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?utf-8?B?YnIxMTFVM2VSRDlFbEZqRFNCNU91cUpwWFhOOXBqYm1vRXMydWlLV2dWcUtL?=
 =?utf-8?B?RWd2SXBOZTlIRmZPOXhGSnpYOGI5cGxCblRVMFpGUlh2ZzRobk9seTNob3Yx?=
 =?utf-8?B?VzlxK0NaakpXdEVtS2dFN1ZwZmtGbmxoVk1ZQ1E3T29yRDNvdHhmRzRWSStt?=
 =?utf-8?B?eDhrSE5wYk9yeDRVMGRPRlFrdEZpRXROd3FCMW9VcjQyUklxTkV5WVQ3TTR0?=
 =?utf-8?B?dTF0amNuK2Q4a3hQUXBUOFpkYjlPem9mS2Zma1ExUHkzTHIvUXZiNHJRSnJJ?=
 =?utf-8?B?TDNJNm1kMEE1UDJKWG11WVZSNysra2ZnVUhVNjZJREthVndCU0owcFdaSWpk?=
 =?utf-8?B?cWRTRzFpNm5USWxWRWgvRFJiYWtvWk9maFhaeHVBSDNwUnBaSHdYMGpncXly?=
 =?utf-8?B?aHZHdzJqeTlxaFp1aUJLOUZVVi9oYjU1TlpPVjBldy9pS2N3am9uWHRaMHBr?=
 =?utf-8?B?SlFuQnZkc2lPZE4vVWpjd2FLcHRvc0RIZVM5d2gvRTRSNnB6NmhVbll6Yk9u?=
 =?utf-8?B?UWdSSXd6TjBuVTlOaXpwTVh1RGtnSUsxTGwxcDI1R0RJWkpqcTEydTRxc0N2?=
 =?utf-8?B?SmNWODNtck5McTRTcVF0Z2o5VUVmRjQvQXpoWUZsRDAwbDJwcithMGNMRUFS?=
 =?utf-8?B?dlZxNXI0ZHpNTVJxdTRMc1dpc3pETHVNcVZaL09mKzJnSDRkdGZuNEc4SFVG?=
 =?utf-8?B?Q1oxbi8zclBTVVdCWVNHRWR5SSsvMTRoeWZXYUNaRk4wZ0Erd0Q4K29kYTF3?=
 =?utf-8?B?T0hlRnNteFBocDFZQmZuV3BGZzdIMEN3S21kc2M1WlZzQTE5Wkl4U3dLM0Jq?=
 =?utf-8?B?WmNGb1NHcUtCWi9GVDNpdnJLWVBUcTljTVFNN0FDaHQrNWE3K1hSVDU1dlVu?=
 =?utf-8?B?d0ZGRDBoNDhxaEdudTdodmQvRVJMM0poMEh6cUc1SzdvL01FdHAzQTUyQWpR?=
 =?utf-8?B?cUsyNVhSUTNkNVFIcmZsNTZFOUhST1BoY3JUM1JSTmo4ZUpnQ0hORTUyWXdG?=
 =?utf-8?B?RU9MZUY2T3VnRWtmdjNscmEwS3AvUC85TzJvL1RkN2RQRDhIVEh2bzNpQ1Zs?=
 =?utf-8?B?ajhXNjdCWjl5ajZiblR0NUlrcVoxdy9MSmZBTmZuQkVaRVFid1FvNDFjMWti?=
 =?utf-8?B?OHVNUkR4SXlaZ25MRUxqQnJ2czB2NzR3WnFPR2RLaXdaL2MzbVRFWW96SVA3?=
 =?utf-8?B?STNyVVJXcUdEWGpYdytWcUxsZ3c0L0dranl0K1VrU2FFUFFlTDNxekZTS1hS?=
 =?utf-8?B?d1htKzExUEtNMWx4UE81QWp5UFp6VGk3OFRJMmlQdGtkVkxDT1llS0pIbnFi?=
 =?utf-8?B?REFxdm0xNDF5cTNCL01CM0p4cXlYMWdjNFFCZHVnMzZYTzFJNGNPcDRvZDRR?=
 =?utf-8?B?bkxrN1Z2ZXRtc3ZUWFJhVVltTmxBT215QXJmTEIxbU9Db0t3YzgyZ0tUeHpT?=
 =?utf-8?B?TDNJL0RHcUZHNmZMMkVuNW1UQjhOWDZLZUI3RkNTaGZjK0FPZld6cDlaajBu?=
 =?utf-8?B?T2hRZ09QdXVid2N4Ukp0bVZSUkxLR1RONUtpVXo3MXd6WUxoa2k1SEJseGtD?=
 =?utf-8?B?U3NvVm8ySW1OSFUvQzErYXRONy8rTmk1UzVmOFU4NnI5UnRGdlhnMUxuYmts?=
 =?utf-8?B?NnBmM3ZPcExGU0QrOVdrTzFqazJTZ3c5Q3ZtTzZ1Z1RsOG1nRFMySzE5aGNY?=
 =?utf-8?B?UEtTdEZZaGJnZnlFbHNid1hvdUthT01UMmR4MkhJMklVZWZ3ckRxdG5SeG54?=
 =?utf-8?B?ZG9JWGY2cldNeHUyd2NHaHFkNEhSclpLOS9WU2NFTzhCQ3RDUTdUaVJWQTJK?=
 =?utf-8?B?TURIYURuWmgwN0F6enNyN0V0MmZCYzloTk1GWUxjT1dUcXNaeE1sT1VjaDZZ?=
 =?utf-8?B?L0o2MXlldmt4WUxOekR3T0dyVVZSNUQwZzluT1Ntd2JDVGVwNzRYNnVnVVlH?=
 =?utf-8?B?UDIwcjFGQWVBTjNKcFNSalVpbkQzdHhrdFhYSU9ncCtHYUdxNFY3RmU2a015?=
 =?utf-8?B?TVZtQWI3MWluWjE0QzYxWnhrcVhYeEpJOE1LM0U4cHFOaFlCRXk5OVpROFJR?=
 =?utf-8?B?RGQrSzdvVnNQaGZCWDY3dCtUQlROWGljVldueXZjS3hINWtOMU50TVdNdWd4?=
 =?utf-8?Q?nZRQrrs0vdJNEdMsgbk+qyBtY?=
X-OriginatorOrg: amd.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 2936d221-5755-4666-f572-08dc33177da5
X-MS-Exchange-CrossTenant-AuthSource: BL1PR12MB5874.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 21 Feb 2024 19:58:36.6614
 (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: KV/2IvlLSfIJg82ksR8sVvrJozIPBZBt5TysZ/1XUiZwxciM5/qpsUZshFgy5UVNZNJiYSCvHq+yKP3G4IGKEw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL1PR12MB5062

Hello,

On 1/9/24 09:56, Carlos Bilbao wrote:
> The general consensus is that the documentation's website main entry point
> and its sidebar leave room for improvement. Something we can easily fix is
> that there's too much duplicated text.
> 
> To that point, consider the titles "The Linux kernel user's and
> administrator's guide" and "The Linux kernel user-space API guide." We get
> it, it's the Linux kernel. It's assumed that everything listed pertains to
> the Linux kernel, given the overarching title, "The Linux Kernel
> documentation." Constant repetition of "Linux" and "kernel" (45 times
> each), "documentation" (21 times), and "guide" (18 times) are excessive and
> affect UX.
> 
> I propose simplifying without altering actual document titles, the text
> linking to these documents on the main page ("link titles"). For example,
> "The Linux kernel user's and administrator's guide" could become "User's
> and Administrator's Guide," and "A guide to the Kernel Development Process"
> could be "Development Process". This is what my patch does.
> 
> Also, I send a patch fixing the formatting of the title of
> admin-guide/index.rst (The Linux kernel user's and administrator's guide);
> a detail I noticed because the link title would not work otherwise.
> 
> Thanks,
> Carlos
> 
> Carlos Bilbao (2):
>      docs: Correct formatting of title in admin-guide/index.rst
>      docs: Include simplified link titles in main index

Is there a reason why this patch set is currently on hold? It must to be
feeling a bit lonely by now.

> 
> ---
> 
> v1 Link: https://lore.kernel.org/lkml/58e78693-82d1-451d-a546-51fb64ef6eb5@vt.edu/T/
> 
> Changes since v1:
> 
> - Apply feedback:
>    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
> 
> - Include patch fixing the title of The Linux kernel user's and
>    administrator's guide.
> 
> - Minor changes: Change "main page's index" for "main index" in commit
>    subject. Also use my work email to sign the commits.
> 
> ---
> Documentation/admin-guide/index.rst |  1 +
> Documentation/index.rst             | 52 ++++++++++++++---------------
> 2 files changed, 27 insertions(+), 26 deletions(-)
> 

Thanks,
Carlos