ksummit.lists.linux.dev archive mirror
 help / color / mirror / Atom feed
From: Linus Walleij <linus.walleij@linaro.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: ksummit <ksummit-discuss@lists.linuxfoundation.org>
Subject: Re: [Ksummit-discuss] [TECH TOPIC] Documentation
Date: Thu, 11 Jun 2020 16:48:21 +0200	[thread overview]
Message-ID: <CACRpkdZOxaA9fpd0zFa_GGo1boOEbOoxNbaUavXbewp=CLbEDg@mail.gmail.com> (raw)
In-Reply-To: <20200609145353.628a342d@lwn.net>

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

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.

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.

Yours,
Linus Walleij
_______________________________________________
Ksummit-discuss mailing list
Ksummit-discuss@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss

  parent reply	other threads:[~2020-06-11 14:48 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 [this message]
2020-06-11 18:03   ` Shuah Khan
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='CACRpkdZOxaA9fpd0zFa_GGo1boOEbOoxNbaUavXbewp=CLbEDg@mail.gmail.com' \
    --to=linus.walleij@linaro.org \
    --cc=corbet@lwn.net \
    --cc=ksummit-discuss@lists.linuxfoundation.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).