From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: MIME-Version: 1.0 In-Reply-To: References: <20170623123936.42dab05f@lwn.net> <20170624074641.4820fecd@vento.lan> <1779146.rtcHP5MkoH@aspire.rjw.lan> <20170624104142.70677fcb@vento.lan> From: Matthew Wilcox Date: Sun, 25 Jun 2017 17:32:31 -0400 Message-ID: To: Mauro Carvalho Chehab Content-Type: multipart/alternative; boundary="001a113edb94744e610552cf9254" Cc: ksummit-discuss@lists.linux-foundation.org Subject: Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , --001a113edb94744e610552cf9254 Content-Type: text/plain; charset="UTF-8" I find documentation comes in the following bins: 1. User documentation (possible sub-split into "how to use this from kernel space" and "how to use this from user space") 2. Information for someone who's interested in modifying the code. Possibly including architectural considerations (eg locking), performance, ideas for future improvement, etc. 3. Random swearing and abuse I think the second and third categories of documentation should be kept out of the kernel books and left as plain comments by the code. On 24 Jun 2017 9:41 am, "Mauro Carvalho Chehab" wrote: Yeah, one of the problems with existing documentation is that, sometimes, the same document describes both userspace-relevant info and kernelspace APIs. --001a113edb94744e610552cf9254 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
I find docum= entation comes in the following bins:

1. User documen= tation (possible sub-split into "how to use this from kernel space&quo= t; and "how to use this from user space")
2. Information for someone who's interested in mo= difying the code. Possibly including architectural considerations (eg locki= ng), performance, ideas for future improvement, etc.
3. Random swearing and abuse

I t= hink the second and third categories of documentation should be kept out of= the kernel books and left as plain comments by the code.

On 24 Jun 2017 9:41 am, &qu= ot;Mauro Carvalho Chehab" <mchehab@s-opensource.com> wrote:
Yeah, o= ne of the problems with existing documentation is that,
sometimes, the same document describes both userspace-relevant
info and kernelspace APIs.
--001a113edb94744e610552cf9254--