ksummit.lists.linux.dev archive mirror
 help / color / mirror / Atom feed
From: Shuah Khan <skhan@linuxfoundation.org>
To: Linus Walleij <linus.walleij@linaro.org>,
	Jonathan Corbet <corbet@lwn.net>
Cc: ksummit <ksummit-discuss@lists.linuxfoundation.org>
Subject: Re: [Ksummit-discuss] [TECH TOPIC] Documentation
Date: Thu, 11 Jun 2020 12:03:21 -0600	[thread overview]
Message-ID: <8f68863a-d04c-4502-f88e-2a8b0e3c7968@linuxfoundation.org> (raw)
In-Reply-To: <CACRpkdZOxaA9fpd0zFa_GGo1boOEbOoxNbaUavXbewp=CLbEDg@mail.gmail.com>

On 6/11/20 8:48 AM, Linus Walleij wrote:
> On Tue, Jun 9, 2020 at 10:54 PM Jonathan Corbet <corbet@lwn.net> 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
Ksummit-discuss@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss

  reply	other threads:[~2020-06-11 18:03 UTC|newest]

Thread overview: 46+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-06-09 20:53 [Ksummit-discuss] [TECH TOPIC] Documentation Jonathan Corbet
2020-06-10  8:49 ` Dan Carpenter
2020-06-11  8:21   ` Daniel Vetter
2020-06-11 14:48 ` Linus Walleij
2020-06-11 18:03   ` Shuah Khan [this message]
2020-06-11 18:28     ` Joe Perches
2020-06-11 19:44       ` Shuah Khan
2020-06-12  8:18         ` Laurent Pinchart
2020-06-12  9:19           ` Mike Rapoport
2020-06-12 10:58             ` Mark Brown
2020-06-12 15:48           ` Shuah Khan
2020-06-12  9:07       ` Mike Rapoport
2020-06-12 16:08         ` Shuah Khan
2020-06-13 16:42           ` Julia Lawall
2020-06-13 16:51             ` Joe Perches
2020-06-13 17:04               ` Julia Lawall
2020-06-14 13:23               ` Matthew Wilcox
2020-06-14 14:13                 ` Mike Rapoport
2020-06-15  9:46               ` Jani Nikula
2020-06-18  9:04               ` Mike Rapoport
2020-06-18 14:40                 ` Joe Perches
     [not found]                   ` <20200709122118.0ffaea91@coco.lan>
2020-07-09 11:42                     ` Joe Perches
2020-07-09 12:11                       ` Mike Rapoport
2020-07-09 16:59                         ` Joe Perches
2020-07-09 17:29                           ` Mike Rapoport
2020-07-09 17:57                             ` Andrew Lunn
     [not found]                               ` <104986.1594328429@turing-police>
2020-07-10  0:03                                 ` Joe Perches
2020-06-13 17:05           ` Laurent Pinchart
2020-06-18  9:08 ` Mike Rapoport
  -- strict thread matches above, loose matches on Subject: below --
2019-06-12 14:54 Jonathan Corbet
2019-06-12 18:22 ` Shuah Khan
2019-06-12 19:12   ` Martin K. Petersen
2019-06-12 19:43     ` Shuah Khan
2019-06-13 14:25   ` Mauro Carvalho Chehab
2019-06-14 21:40     ` Shuah Khan
2019-06-15  0:05       ` Mauro Carvalho Chehab
2019-06-17 10:12         ` Mauro Carvalho Chehab
2019-06-17 17:21           ` Mauro Carvalho Chehab
2019-06-12 20:33 ` Kate Stewart
2019-06-13 14:17   ` Mauro Carvalho Chehab
2019-06-13 14:57 ` Mauro Carvalho Chehab
2019-06-13 18:48   ` Greg KH
2019-06-13 19:01     ` Mauro Carvalho Chehab
2019-06-20 18:36 ` Kees Cook
2019-06-20 19:28   ` Jonathan Corbet
2019-07-22 14:52 ` Mauro Carvalho Chehab

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8f68863a-d04c-4502-f88e-2a8b0e3c7968@linuxfoundation.org \
    --to=skhan@linuxfoundation.org \
    --cc=corbet@lwn.net \
    --cc=ksummit-discuss@lists.linuxfoundation.org \
    --cc=linus.walleij@linaro.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).