Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

[Jonathan Corbet]

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

So I totally agree that the sidebar can use improvement, and I agree
that this patch makes it better.

I'm less convinced about the changes to the page itself, which I
consider to be somewhat more important.  There, I think, the more terse
titles are likely to be less useful for readers.  (OTOH, I think the
result is an improvement for those reading the RST files).

I spent some time a little while back understanding how the sidebar is
generated, and feel that we can make it into what we want it to be.  But
I don't think we've decided what we really want it to be.  I think there
is simply too much stuff there in general; it's never going to be
manageable that way.

There was a suggestion at the kernel-summit session to just put the
top-level books there:

	Kernel documentation
        Development-process guide
        Core API manual
        Driver API manual
        User-space API manual
        Maintainer guide
        Documentation guide

Then perhaps add one level for whichever book is open (if any) at the
time.

I'm sure there are other, better ideas as well.

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

...so it's not necessary to build the docs to see the results.

Thanks,

jon

Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

[Carlos Bilbao]

On 12/15/23 09: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.
>>
>> 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.
> 
> So I totally agree that the sidebar can use improvement, and I agree
> that this patch makes it better.
> 
> I'm less convinced about the changes to the page itself, which I
> consider to be somewhat more important.  There, I think, the more terse
> titles are likely to be less useful for readers.  (OTOH, I think the
> result is an improvement for those reading the RST files).
> 
> I spent some time a little while back understanding how the sidebar is
> generated, and feel that we can make it into what we want it to be.  But
> I don't think we've decided what we really want it to be.  I think there
> is simply too much stuff there in general; it's never going to be
> manageable that way.
> 
> There was a suggestion at the kernel-summit session to just put the
> top-level books there:
> 
> 	Kernel documentation
>          Development-process guide
>          Core API manual
>          Driver API manual
>          User-space API manual
>          Maintainer guide
>          Documentation guide
> 
> Then perhaps add one level for whichever book is open (if any) at the
> time.

I like this idea; as of today, we have too many duplicated links.

Regarding the addition of concise titles for the link titles, I'd argue
that the important part is not to lose information. For example, I
shortened "Submitting patches: the essential guide to getting your code
into the kernel" to "Submitting patches". But, if I had simply put
"Patches", it would have made it unclear what the document was actually
about.

> 
> I'm sure there are other, better ideas as well.
> 
> 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
> 
> ...so it's not necessary to build the docs to see the results.
> 
> Thanks,
> 
> jon
> 

Thanks,
Carlos

Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

[Vegard Nossum]

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


Vegard

Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

[Randy Dunlap]

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

Re: [PATCH 0/1] docs: Include simplified link titles in main page's index

[Carlos Bilbao]

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