mbox series

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

Message ID 20221118170942.2588412-1-carlos.bilbao@amd.com
Headers
Series kernel-docs: New maintainer and Spanish translation |

Message

Carlos Bilbao Nov. 18, 2022, 5:09 p.m. UTC 
  This is a cover letter for just two patches, but I should provide context.
I was going to translate kernel-docs.rst when I read:

“Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>;
email address is defunct now.)“

I figured Juan-Mariano (CCed) may keep a Spanish version of the document,
so I searched for his new email. He replied back proposing me to take care
of the document from now on. I will carry the torch with pleasure! This
should also make Lukas happy [1].

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.

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.

I also use this chance to send translation to Spanish of the document.

[1] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/Documentation/process/kernel-docs.rst?h=next-20221116&id=f46b4b168cdb3b16ae8c7792c28d0b921db1932b

Carlos Bilbao (2):
 docs: Update maintainer of kernel-docs.rst
 docs/sp_SP: Add process kernel-docs translation 

---
 Documentation/process/kernel-docs.rst         |   4 +-
 Documentation/translations/sp_SP/index.rst    |   2 +-
 .../translations/sp_SP/kernel-docs.rst        | 643 ++++++++++++++++++
 3 files changed, 646 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/translations/sp_SP/kernel-docs.rst

Comments

Miguel Ojeda Nov. 18, 2022, 5:56 p.m. UTC | #1 
On Fri, Nov 18, 2022 at 6:09 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
> This is a cover letter for just two patches, but I should provide context.
> I was going to translate kernel-docs.rst when I read:
>
> “Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>;
> email address is defunct now.)“
>
> I figured Juan-Mariano (CCed) may keep a Spanish version of the document,
> so I searched for his new email. He replied back proposing me to take care
> of the document from now on. I will carry the torch with pleasure! This
> should also make Lukas happy [1].

Maybe some of this context could go into one commit message so that it
is recorded in Git.

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

Indeed, updates would be appreciated!

Cheers,
Miguel
Carlos Bilbao Nov. 18, 2022, 6:30 p.m. UTC | #2 
On 11/18/22 11:56, Miguel Ojeda wrote:

> On Fri, Nov 18, 2022 at 6:09 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>> This is a cover letter for just two patches, but I should provide context.
>> I was going to translate kernel-docs.rst when I read:
>>
>> “Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>;
>> email address is defunct now.)“
>>
>> I figured Juan-Mariano (CCed) may keep a Spanish version of the document,
>> so I searched for his new email. He replied back proposing me to take care
>> of the document from now on. I will carry the torch with pleasure! This
>> should also make Lukas happy [1].
> Maybe some of this context could go into one commit message so that it
> is recorded in Git.


That's true. But I don't think if I'll be able to synthesize the whole
story in a few words. I could add a Link: to this first cover letter.


>
>> 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.
> Indeed, updates would be appreciated!
>
> Cheers,
> Miguel


Thanks,
Carlos
Jonathan Corbet Nov. 21, 2022, 8:58 p.m. UTC | #3 
Carlos Bilbao <carlos.bilbao@amd.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.

> 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
Carlos Bilbao Nov. 23, 2022, 4:19 p.m. UTC | #4 
On 11/21/22 2:58 PM, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao@amd.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
Jonathan Corbet Nov. 23, 2022, 4:22 p.m. UTC | #5 
Carlos Bilbao <carlos.bilbao@amd.com> writes:

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

I'm certainly not opposed to trying! :)

Thanks,

jon
Carlos Bilbao Nov. 24, 2022, 3:40 p.m. UTC | #6 
On 11/23/22 10:22, Jonathan Corbet wrote:

> Carlos Bilbao <carlos.bilbao@amd.com> writes:
>
>> 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?
> I'm certainly not opposed to trying! :)


I'm starting a new patch set with this, and translating coding-style.rst,
after fixing the organization of sp_SP/.


>
> Thanks,
>
> jon


Thanks,

Carlos