linux-kernel - Re: [PATCH 0/2] kernel-docs: New maintainer and Spanish translation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <093907af-2e4e-d232-1eb0-7331ff2b9320@amd.com>
Date:   Wed, 23 Nov 2022 10:19:40 -0600
From:   Carlos Bilbao <carlos.bilbao@....com>
To:     Jonathan Corbet <corbet@....net>, lukas.bulwahn@...il.com
Cc:     linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org,
        bilbao@...edu, ojeda@...nel.org, lstoakes@...il.com
Subject: Re: [PATCH 0/2] kernel-docs: New maintainer and Spanish translation

On 11/21/22 2:58 PM, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@....com> writes:
> 
>> This cover letter is also a call for anyone interested in adding new, more
>> up to date references to kernel-docs.rst. The document has been abandoned
>> for a while but its original goal is still important.
> 
> FWIW, I made an attempt to update this document a few years back and
> concluded that it was pretty much hopeless.  What is there is
> ancient...what do you replace it with?  There is a vast amount of
> content out there that will go obsolete just as quickly.
> 
> I'm certainly not going to stand in the way of anybody who wants to
> update and maintain this document, though; I'd love to be proven wrong
> on its value.
> 

I gather there's two issues with this document:

1. The resources listed become obsolete, or dangerously outdated.

2. It requires periodic updates. Relying on some maintainer to keep updates
of new kernel material is a bad long-term strategy.

so perhaps we could try the following...

Regarding (1), old resources should be removed. We could set the retirement
age of a resource to 3 years, except for foundational books or active
websites. As maintainer, I would have to group old stuff once or twice per 
year, and send a patch to get them removed. We could use this patch set to
perform a first purge.

For (2), I think that a good way to make this document stay relevant is by
making it appealing to content creators. So _they_ want to be added here,
and ask us for it.

For example, Lorenzo Stoakes (CCed) is writing a book on the Linux memory
management subsystem. If Lorenzo reaches out to me when he is finished,
I could add his work to this document, and also send a note informing
subscribers of linux-docs about this new resource. I imagine that would be
appealing to Lorenzo.

So basically, if content creators reach out, they get free publicity and
a spot in kernel-docs.rst. I imagine there's only a few publishers of
books related to the Linux kernel, and that they might be interested.

As maintainer I would still have to update the document. But the hope is
that, with time, this document is better known and book writers reach out.

I don't know if that would have any success. Worst-case scenario, we end up
with an equally outdated list of resources in a few years. But maybe it's
worth a try?

Cheers,
Carlos

>> By the way, Jon, I read in kernel-docs.rst, regarding LWN.net:
>>
>> ":Description: The title says it all. There's a fixed kernel section
>>   summarizing developers' work, bug fixes, new features and versions
>>   produced during the week. Published every Thursday."
>>
>> but I don't think LWN.net is published every Thursday anymore. Let me know
>> if you want a third patch updating this as well.
> 
> Well, we do still put out an edition every Thursday, so it's not
> entirely wrong...
> 
> Thanks,
> 
> jon