Re: [Ksummit-discuss] [TECH TOPIC] Documentation

On 6/11/20 8:48 AM, Linus Walleij wrote:
> On Tue, Jun 9, 2020 at 10:54 PM Jonathan Corbet <[email protected]> wrote:
> 
>> What are the next steps for kernel documentation?  What would we really
>> like our docs to look like, and how might we find the resources to get
>> them to that point?
> 
> We have a whole slew of quite basic introductory materials to the very
> fundamental kernel data structures that are scattered all over the planet
> and in the LWN kernel archive. All in often slightly dated variants.
> Examples:
> https://www.kernel.org/doc/gorman/html/understand/understand006.html
> http://vger.kernel.org/~davem/skb_data.html
> 
> I suppose technical writers could benefit from a global TODO list with
> this kind of subjects such as "document the basic arch interface",
> "document what an skb is", "document how the page directory works".
> 

I totally agree. A solid TODO list is necessary to channel efforts.

> Right now it is a mixture of read the code, "everybody knows how that
> works" and random sources on the Internet, which isn't very helpful
> to newcomers.
> 

Also true. I New comers are intimidated to ask questions in the first
place and they might not get responses. It boils down to bandwidth
more often than not. People that know the sub-systems well might not
have time to document and more importantly keeping the documents
updated.

> I second Vetters point to tie this documentation in tightly with the code
> implementing it even pretty substantial text chunks IMO, the idea can be
> attributed to Donald Knuth's book on literate programming from 1984,
> and while he was a bit enthusiastic the idea isn't bad at all.
> 

It definitely helps to that. I do see lots of calls without no comments
and usage information. For this to work, we have to give feedback during
the review process. This is necessary for commit logs as well.

I am interested in this topic as I help new developers and I often hear
the same concern that there aren't resources for them to learn and
understand kernel subsystems.

I have been reaching out to new contributors to kernel for the last
6 releases starting with Linux 5.1 asking

"What suggestions do you have for improving the materials and guidance
available to new contributors?"

The feedback always is request for updated information in kernel
documentation and online resources. I will be glad to share detailed
feedback if there is interest.

Addressing the need in providing kernel documentation could address
the need.

thanks,
-- Shuah
_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss