Received-SPF: pass (google.com: domain of linux-kernel+bounces-21083-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
Received-SPF: Pass (protection.outlook.com: domain of amd.com designates
 165.204.84.17 as permitted sender) receiver=protection.outlook.com;
 client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C
From: Carlos Bilbao <carlos.bilbao@amd.com>
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>, Carlos Bilbao <carlos.bilbao@amd.com>
Subject: [PATCH v2 0/2] docs: Include simplified link titles in main index
Date: Tue, 9 Jan 2024 09:56:41 -0600
Message-ID: <20240109155643.3489369-1-carlos.bilbao@amd.com>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 Jan 2024 15:56:44.9507
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: bf5ad3dc-33b1-40c9-8ce2-08dc112b9468
X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB04.amd.com]
X-MS-Exchange-CrossTenant-AuthSource:
	CO1PEPF000044F8.namprd21.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ1PR12MB6169

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

---

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(-)