From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D0864B647; Thu, 21 Dec 2023 06:12:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="0QKCcYhe" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: Content-Type:In-Reply-To:From:References:Cc:To:Subject:MIME-Version:Date: Message-ID:Sender:Reply-To:Content-ID:Content-Description; bh=fEMnsN9fKsacrZv+PZoSB1BdLYTdkoVYZcEdsoJrm0c=; b=0QKCcYhei8MIe3PofdWJOU/whE Sr+aBpUIB950oRXoDWH3KzwU6M6Xi/fTyaG6Jmuxk3+y97Bhae3xsHqbjn6zptXyUVGDI6GRbwdjQ 6irkAnBpJaQYJLrf1U8tOeUHVN6yUToiAF46w/Mvc5sHXax5Jm8Vqmu5i+TMmJaY5+nkewazeZnf+ eU8zOauAqwJLsQiq2EPNkczGlZAgF4ihlq68hogAzTFQNdPcQwYUKHmqRF2qaAA7fCdLBfudfjU9W J35Zyf7JIMSki1DzGKodv27CMMIyHW4CU25QxWGn2QASc99gsP4rplySZFxwWKa8vNYGhD7idK/ZM j42TQlqg==; Received: from [50.53.46.231] (helo=[192.168.254.15]) by bombadil.infradead.org with esmtpsa (Exim 4.96 #2 (Red Hat Linux)) id 1rGCHp-001nrQ-0L; Thu, 21 Dec 2023 06:12:02 +0000 Message-ID: Date: Wed, 20 Dec 2023 22:11:58 -0800 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: 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 , Jonathan Corbet , Carlos Bilbao , Miguel Ojeda Cc: Alex Gaynor , Wedson Almeida Filho , Boqun Feng , Gary Guo , =?UTF-8?Q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , 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> From: Randy Dunlap In-Reply-To: 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 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