From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-qk0-f200.google.com (mail-qk0-f200.google.com [209.85.220.200])
	by kanga.kvack.org (Postfix) with ESMTP id 45C256B0006
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 05:54:59 -0500 (EST)
Received: by mail-qk0-f200.google.com with SMTP id k188so6734787qkc.18
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 02:54:59 -0800 (PST)
Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com. [148.163.156.1])
        by mx.google.com with ESMTPS id q2si1900797qkq.13.2018.01.30.02.54.58
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Tue, 30 Jan 2018 02:54:58 -0800 (PST)
Received: from pps.filterd (m0098404.ppops.net [127.0.0.1])
	by mx0a-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w0UAsTiu011630
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 05:54:57 -0500
Received: from e06smtp13.uk.ibm.com (e06smtp13.uk.ibm.com [195.75.94.109])
	by mx0a-001b2d01.pphosted.com with ESMTP id 2ftnn4d0u3-1
	(version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT)
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 05:54:57 -0500
Received: from localhost
	by e06smtp13.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted
	for <linux-mm@kvack.org> from <rppt@linux.vnet.ibm.com>;
	Tue, 30 Jan 2018 10:54:55 -0000
Date: Tue, 30 Jan 2018 12:54:50 +0200
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
References: <20180130105237.GB7201@rapoport-lnx>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180130105237.GB7201@rapoport-lnx>
Message-Id: <20180130105450.GC7201@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: lsf-pc@lists.linux-foundation.org
Cc: linux-mm@kvack.org

(forgot to CC linux-mm)

On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> Hello,
> 
> The mm kernel-doc documentation is not in a great shape. 
> 
> Some of the existing kernel-doc annotations were not reformatted during
> transition from dockbook to sphix. Sometimes the parameter descriptions
> do not match actual code. But aside these rather mechanical issues there
> are several points it'd like to discuss:
> 
> * Currently, only 14 files are linked to kernel-api.rst under "Memory
> Management in Linux" section. We have more than hundred files only in mm.
> Even the existing documentation is not generated when running "make
> htmldocs"
> * Do we want to keep "Memory Management in Linux" under kernel-api.rst or
> maybe it's worth adding, say, mm.rst?
> * What is the desired layout of the documentation, what sections we'd like
> to have, how the documentation should be ordered?
> 
> -- 
> Sincerely yours,
> Mike.

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-wm0-f69.google.com (mail-wm0-f69.google.com [74.125.82.69])
	by kanga.kvack.org (Postfix) with ESMTP id 3DF226B0005
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 06:50:58 -0500 (EST)
Received: by mail-wm0-f69.google.com with SMTP id e195so80182wmd.9
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 03:50:58 -0800 (PST)
Received: from mx2.suse.de (mx2.suse.de. [195.135.220.15])
        by mx.google.com with ESMTPS id r60si5343166wrb.135.2018.01.30.03.50.56
        for <linux-mm@kvack.org>
        (version=TLS1 cipher=AES128-SHA bits=128/128);
        Tue, 30 Jan 2018 03:50:57 -0800 (PST)
Date: Tue, 30 Jan 2018 12:50:55 +0100
From: Michal Hocko <mhocko@kernel.org>
Subject: Re: [LSF/MM TOPIC] mm documentation
Message-ID: <20180130115055.GZ21609@dhcp22.suse.cz>
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180130105450.GC7201@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Mike Rapoport <rppt@linux.vnet.ibm.com>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> (forgot to CC linux-mm)
> 
> On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> > Hello,
> > 
> > The mm kernel-doc documentation is not in a great shape. 
> > 
> > Some of the existing kernel-doc annotations were not reformatted during
> > transition from dockbook to sphix. Sometimes the parameter descriptions
> > do not match actual code. But aside these rather mechanical issues there
> > are several points it'd like to discuss:
> > 
> > * Currently, only 14 files are linked to kernel-api.rst under "Memory
> > Management in Linux" section. We have more than hundred files only in mm.
> > Even the existing documentation is not generated when running "make
> > htmldocs"

Is this documentation anywhere close to be actually useful?
-- 
Michal Hocko
SUSE Labs

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-qt0-f197.google.com (mail-qt0-f197.google.com [209.85.216.197])
	by kanga.kvack.org (Postfix) with ESMTP id D36686B0008
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 07:55:05 -0500 (EST)
Received: by mail-qt0-f197.google.com with SMTP id k11so10875001qth.23
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 04:55:05 -0800 (PST)
Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com. [148.163.156.1])
        by mx.google.com with ESMTPS id t126si3893288qkb.474.2018.01.30.04.55.04
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Tue, 30 Jan 2018 04:55:05 -0800 (PST)
Received: from pps.filterd (m0098409.ppops.net [127.0.0.1])
	by mx0a-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w0UCsjo3133710
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 07:55:04 -0500
Received: from e06smtp13.uk.ibm.com (e06smtp13.uk.ibm.com [195.75.94.109])
	by mx0a-001b2d01.pphosted.com with ESMTP id 2ftqv4uh7f-1
	(version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT)
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 07:55:02 -0500
Received: from localhost
	by e06smtp13.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted
	for <linux-mm@kvack.org> from <rppt@linux.vnet.ibm.com>;
	Tue, 30 Jan 2018 12:54:50 -0000
Date: Tue, 30 Jan 2018 14:54:44 +0200
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180130115055.GZ21609@dhcp22.suse.cz>
Message-Id: <20180130125443.GA21333@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Michal Hocko <mhocko@kernel.org>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
> On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> > (forgot to CC linux-mm)
> > 
> > On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> > > Hello,
> > > 
> > > The mm kernel-doc documentation is not in a great shape. 
> > > 
> > > Some of the existing kernel-doc annotations were not reformatted during
> > > transition from dockbook to sphix. Sometimes the parameter descriptions
> > > do not match actual code. But aside these rather mechanical issues there
> > > are several points it'd like to discuss:
> > > 
> > > * Currently, only 14 files are linked to kernel-api.rst under "Memory
> > > Management in Linux" section. We have more than hundred files only in mm.
> > > Even the existing documentation is not generated when running "make
> > > htmldocs"
> 
> Is this documentation anywhere close to be actually useful?

Some parts are documented better, some worse. For instance, bootmem and
z3fold are covered not bad at all, but, say, huge_memory has no structured
comments at all. Roughly half of the files in mm/ have some documentation,
but I didn't yet read that all to say how much of it is actually useful.

And maybe having some skeleton for MM API in htmldocs with at least some
documentation will encourage people to look at the documentation.

> -- 
> Michal Hocko
> SUSE Labs
> 

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-wm0-f71.google.com (mail-wm0-f71.google.com [74.125.82.71])
	by kanga.kvack.org (Postfix) with ESMTP id 4C75B6B0005
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 08:41:45 -0500 (EST)
Received: by mail-wm0-f71.google.com with SMTP id a6so266202wme.9
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 05:41:45 -0800 (PST)
Received: from mx2.suse.de (mx2.suse.de. [195.135.220.15])
        by mx.google.com with ESMTPS id b133si9492883wme.171.2018.01.30.05.41.43
        for <linux-mm@kvack.org>
        (version=TLS1 cipher=AES128-SHA bits=128/128);
        Tue, 30 Jan 2018 05:41:43 -0800 (PST)
Date: Tue, 30 Jan 2018 14:41:41 +0100
From: Michal Hocko <mhocko@kernel.org>
Subject: Re: [LSF/MM TOPIC] mm documentation
Message-ID: <20180130134141.GD21609@dhcp22.suse.cz>
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180130125443.GA21333@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Mike Rapoport <rppt@linux.vnet.ibm.com>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue 30-01-18 14:54:44, Mike Rapoport wrote:
> On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
> > On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> > > (forgot to CC linux-mm)
> > > 
> > > On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> > > > Hello,
> > > > 
> > > > The mm kernel-doc documentation is not in a great shape. 
> > > > 
> > > > Some of the existing kernel-doc annotations were not reformatted during
> > > > transition from dockbook to sphix. Sometimes the parameter descriptions
> > > > do not match actual code. But aside these rather mechanical issues there
> > > > are several points it'd like to discuss:
> > > > 
> > > > * Currently, only 14 files are linked to kernel-api.rst under "Memory
> > > > Management in Linux" section. We have more than hundred files only in mm.
> > > > Even the existing documentation is not generated when running "make
> > > > htmldocs"
> > 
> > Is this documentation anywhere close to be actually useful?
> 
> Some parts are documented better, some worse. For instance, bootmem and
> z3fold are covered not bad at all, but, say, huge_memory has no structured
> comments at all. Roughly half of the files in mm/ have some documentation,
> but I didn't yet read that all to say how much of it is actually useful.

It is good to hear that at least something has a documentation coverage.
I was asking mostly because I _think_ that the API documentation is far
from the top priority. We are seriously lacking any highlevel one which
describes the design and subsytems interaction. Well, we have missed
that train years ago. It will be really hard to catch up.

-- 
Michal Hocko
SUSE Labs

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-qt0-f197.google.com (mail-qt0-f197.google.com [209.85.216.197])
	by kanga.kvack.org (Postfix) with ESMTP id D1ADE6B0006
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 09:28:58 -0500 (EST)
Received: by mail-qt0-f197.google.com with SMTP id f16so11144223qth.20
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 06:28:58 -0800 (PST)
Received: from mx0a-001b2d01.pphosted.com (mx0b-001b2d01.pphosted.com. [148.163.158.5])
        by mx.google.com with ESMTPS id o62si467059qka.371.2018.01.30.06.28.57
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Tue, 30 Jan 2018 06:28:58 -0800 (PST)
Received: from pps.filterd (m0098413.ppops.net [127.0.0.1])
	by mx0b-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w0UEPg62136038
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 09:28:57 -0500
Received: from e06smtp11.uk.ibm.com (e06smtp11.uk.ibm.com [195.75.94.107])
	by mx0b-001b2d01.pphosted.com with ESMTP id 2ftqxhr3wk-1
	(version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT)
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 09:28:57 -0500
Received: from localhost
	by e06smtp11.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted
	for <linux-mm@kvack.org> from <rppt@linux.vnet.ibm.com>;
	Tue, 30 Jan 2018 14:28:55 -0000
Date: Tue, 30 Jan 2018 16:28:50 +0200
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx>
 <20180130134141.GD21609@dhcp22.suse.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180130134141.GD21609@dhcp22.suse.cz>
Message-Id: <20180130142849.GD21333@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Michal Hocko <mhocko@kernel.org>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
> On Tue 30-01-18 14:54:44, Mike Rapoport wrote:
> > On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
> > > On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> > > > (forgot to CC linux-mm)
> > > > 
> > > > On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> > > > > Hello,
> > > > > 
> > > > > The mm kernel-doc documentation is not in a great shape. 
> > > > > 
> > > > > Some of the existing kernel-doc annotations were not reformatted during
> > > > > transition from dockbook to sphix. Sometimes the parameter descriptions
> > > > > do not match actual code. But aside these rather mechanical issues there
> > > > > are several points it'd like to discuss:
> > > > > 
> > > > > * Currently, only 14 files are linked to kernel-api.rst under "Memory
> > > > > Management in Linux" section. We have more than hundred files only in mm.
> > > > > Even the existing documentation is not generated when running "make
> > > > > htmldocs"
> > > 
> > > Is this documentation anywhere close to be actually useful?
> > 
> > Some parts are documented better, some worse. For instance, bootmem and
> > z3fold are covered not bad at all, but, say, huge_memory has no structured
> > comments at all. Roughly half of the files in mm/ have some documentation,
> > but I didn't yet read that all to say how much of it is actually useful.
> 
> It is good to hear that at least something has a documentation coverage.
> I was asking mostly because I _think_ that the API documentation is far
> from the top priority. 

API documentations is important for kernel developers who are not deeply
involved with mm. When one develops a device driver, knowing how to
allocate and free memory is essential. And, while *malloc are included in
kernel-api.rst, CMA and HMM documentation is not visible.

> We are seriously lacking any highlevel one which describes the design and
> subsytems interaction.

I should have describe it better, but by "creating a new structure for mm
documentation" I've also meant adding high level description.

> Well, we have missed that train years ago. It will be really hard to catch up.

At least we can try.

> -- 
> Michal Hocko
> SUSE Labs
> 

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-pg0-f71.google.com (mail-pg0-f71.google.com [74.125.83.71])
	by kanga.kvack.org (Postfix) with ESMTP id 6E0F56B0005
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 12:32:09 -0500 (EST)
Received: by mail-pg0-f71.google.com with SMTP id e12so8304628pgu.11
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 09:32:09 -0800 (PST)
Received: from bombadil.infradead.org (bombadil.infradead.org. [65.50.211.133])
        by mx.google.com with ESMTPS id c8-v6si2507824pli.19.2018.01.30.09.32.07
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
        Tue, 30 Jan 2018 09:32:07 -0800 (PST)
Subject: Re: [LSF/MM TOPIC] mm documentation
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx> <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx> <20180130134141.GD21609@dhcp22.suse.cz>
 <20180130142849.GD21333@rapoport-lnx>
From: Randy Dunlap <rdunlap@infradead.org>
Message-ID: <8e8353c2-f985-2da0-d880-25992097cbf6@infradead.org>
Date: Tue, 30 Jan 2018 09:32:04 -0800
MIME-Version: 1.0
In-Reply-To: <20180130142849.GD21333@rapoport-lnx>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Mike Rapoport <rppt@linux.vnet.ibm.com>, Michal Hocko <mhocko@kernel.org>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On 01/30/2018 06:28 AM, Mike Rapoport wrote:
> On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
>> On Tue 30-01-18 14:54:44, Mike Rapoport wrote:
>>> On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
>>>> On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
>>>>> (forgot to CC linux-mm)
>>>>>
>>>>> On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
>>>>>> Hello,
>>>>>>
>>>>>> The mm kernel-doc documentation is not in a great shape. 
>>>>>>
>>>>>> Some of the existing kernel-doc annotations were not reformatted during
>>>>>> transition from dockbook to sphix. Sometimes the parameter descriptions
>>>>>> do not match actual code. But aside these rather mechanical issues there
>>>>>> are several points it'd like to discuss:
>>>>>>
>>>>>> * Currently, only 14 files are linked to kernel-api.rst under "Memory
>>>>>> Management in Linux" section. We have more than hundred files only in mm.
>>>>>> Even the existing documentation is not generated when running "make
>>>>>> htmldocs"
>>>>
>>>> Is this documentation anywhere close to be actually useful?
>>>
>>> Some parts are documented better, some worse. For instance, bootmem and
>>> z3fold are covered not bad at all, but, say, huge_memory has no structured
>>> comments at all. Roughly half of the files in mm/ have some documentation,
>>> but I didn't yet read that all to say how much of it is actually useful.
>>
>> It is good to hear that at least something has a documentation coverage.
>> I was asking mostly because I _think_ that the API documentation is far
>> from the top priority. 
> 
> API documentations is important for kernel developers who are not deeply
> involved with mm. When one develops a device driver, knowing how to
> allocate and free memory is essential. And, while *malloc are included in
> kernel-api.rst, CMA and HMM documentation is not visible.
> 
>> We are seriously lacking any highlevel one which describes the design and
>> subsytems interaction.
> 
> I should have describe it better, but by "creating a new structure for mm
> documentation" I've also meant adding high level description.
> 
>> Well, we have missed that train years ago. It will be really hard to catch up.
> 
> At least we can try.

Hi,
I would move it all to a new mm.rst file.  That would be easier to maintain
and also allow parallel building.

-- 
~Randy

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-pg0-f72.google.com (mail-pg0-f72.google.com [74.125.83.72])
	by kanga.kvack.org (Postfix) with ESMTP id B49386B0007
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 12:35:36 -0500 (EST)
Received: by mail-pg0-f72.google.com with SMTP id 66so8341926pgh.2
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 09:35:36 -0800 (PST)
Received: from bedivere.hansenpartnership.com (bedivere.hansenpartnership.com. [66.63.167.143])
        by mx.google.com with ESMTPS id a1-v6si4355477plt.588.2018.01.30.09.35.35
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
        Tue, 30 Jan 2018 09:35:35 -0800 (PST)
Message-ID: <1517333732.3118.49.camel@HansenPartnership.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
From: James Bottomley <James.Bottomley@HansenPartnership.com>
Date: Tue, 30 Jan 2018 09:35:32 -0800
In-Reply-To: <20180130142849.GD21333@rapoport-lnx>
References: <20180130105237.GB7201@rapoport-lnx>
	 <20180130105450.GC7201@rapoport-lnx>
	 <20180130115055.GZ21609@dhcp22.suse.cz>
	 <20180130125443.GA21333@rapoport-lnx>
	 <20180130134141.GD21609@dhcp22.suse.cz>
	 <20180130142849.GD21333@rapoport-lnx>
Content-Type: text/plain; charset="UTF-8"
Mime-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Mike Rapoport <rppt@linux.vnet.ibm.com>, Michal Hocko <mhocko@kernel.org>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue, 2018-01-30 at 16:28 +0200, Mike Rapoport wrote:
> On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
> > 
> > On Tue 30-01-18 14:54:44, Mike Rapoport wrote:
> > > 
> > > On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
> > > > 
> > > > On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> > > > > 
> > > > > (forgot to CC linux-mm)
> > > > > 
> > > > > On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport
> > > > > wrote:
> > > > > > 
> > > > > > Hello,
> > > > > > 
> > > > > > The mm kernel-doc documentation is not in a great shape.A 
> > > > > > 
> > > > > > Some of the existing kernel-doc annotations were not
> > > > > > reformatted during transition from dockbook to sphix.
> > > > > > Sometimes the parameter descriptions do not match actual
> > > > > > code. But aside these rather mechanical issues there
> > > > > > are several points it'd like to discuss:
> > > > > > 
> > > > > > * Currently, only 14 files are linked to kernel-api.rst
> > > > > > under "Memory Management in Linux" section. We have more
> > > > > > than hundred files only in mm. Even the existing
> > > > > > documentation is not generated when running "make
> > > > > > htmldocs"
> > > > 
> > > > Is this documentation anywhere close to be actually useful?
> > > 
> > > Some parts are documented better, some worse. For instance,
> > > bootmem and z3fold are covered not bad at all, but, say,
> > > huge_memory has no structured comments at all. Roughly half of
> > > the files in mm/ have some documentation, but I didn't yet read
> > > that all to say how much of it is actually useful.
> > 
> > It is good to hear that at least something has a documentation
> > coverage. I was asking mostly because I _think_ that the API
> > documentation is far from the top priority.A 
> 
> API documentations is important for kernel developers who are not
> deeply involved with mm. When one develops a device driver, knowing
> how to allocate and free memory is essential. And, while *malloc are
> included in kernel-api.rst, CMA and HMM documentation is not visible.

Documentation is also one way new people get into the project.A A Not
being top priority is fine, but "far from" top priority implies not
worth doing, which gives the wrong impression.

> > We are seriously lacking any highlevel one which describes the
> > design and subsytems interaction.
> 
> I should have describe it better, but by "creating a new structure
> for mm documentation" I've also meant adding high level description.
> 
> > 
> > Well, we have missed that train years ago. It will be really hard
> > to catch up.
> 
> At least we can try.

How about simply insisting on adequately documenting new stuff and
asking submitters to add documentation when they change something.A A The
latter, at least, is fairly essential: there's nothing worse than
documentation that's actively wrong. A The former is useful to
reviewers. A I'm not saying this alone will ever get you to 100%, but at
least it's an incremental change which isn't too burdensome and which
moves the needle in the right direction.

James

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-pg0-f72.google.com (mail-pg0-f72.google.com [74.125.83.72])
	by kanga.kvack.org (Postfix) with ESMTP id 1E3CA6B0005
	for <linux-mm@kvack.org>; Tue, 30 Jan 2018 21:38:42 -0500 (EST)
Received: by mail-pg0-f72.google.com with SMTP id e28so9415483pgn.23
        for <linux-mm@kvack.org>; Tue, 30 Jan 2018 18:38:42 -0800 (PST)
Received: from bombadil.infradead.org (bombadil.infradead.org. [65.50.211.133])
        by mx.google.com with ESMTPS id s10si10232724pgv.654.2018.01.30.18.38.40
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
        Tue, 30 Jan 2018 18:38:40 -0800 (PST)
Date: Tue, 30 Jan 2018 18:38:38 -0800
From: Matthew Wilcox <willy@infradead.org>
Subject: Re: [LSF/MM TOPIC] mm documentation
Message-ID: <20180131023838.GA28275@bombadil.infradead.org>
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx>
 <20180130134141.GD21609@dhcp22.suse.cz>
 <20180130142849.GD21333@rapoport-lnx>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180130142849.GD21333@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Mike Rapoport <rppt@linux.vnet.ibm.com>
Cc: Michal Hocko <mhocko@kernel.org>, lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue, Jan 30, 2018 at 04:28:50PM +0200, Mike Rapoport wrote:
> On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
> > It is good to hear that at least something has a documentation coverage.
> > I was asking mostly because I _think_ that the API documentation is far
> > from the top priority. 
> 
> API documentations is important for kernel developers who are not deeply
> involved with mm. When one develops a device driver, knowing how to
> allocate and free memory is essential. And, while *malloc are included in
> kernel-api.rst, CMA and HMM documentation is not visible.
> 
> > We are seriously lacking any highlevel one which describes the design and
> > subsytems interaction.
> 
> I should have describe it better, but by "creating a new structure for mm
> documentation" I've also meant adding high level description.

We should be really clear what kind of documentation we're trying to create.

There are four distinct types of documentation which would be useful:

 - How, when and why to use the various function calls and their
   parameters from the perspective of a user outside the mm/ hierarchy.
   Device driver authors, filesystem authors and others of their ilk.
 - The overall philosophy and structure of the mm directory, what it does,
   why it does it, perhaps even outlines of abandoned approaches.
 - What functionality the mm subsystem requires from others.  For example,
   what does the mm rely on from the CPU architectures (and maybe it would
   make sense to also include services the mm layer provides to arches in
   this section, like setting up sparsemem).
 - How to tweak the various knobs that the mm subsystem provides.
   Maybe this is all adequately documented elsewhere already.

Perhaps others can think of other types of documentation which would
be useful.  That shouldn't detract from my main point, which is that
saying "Now we have mm documentation" is laudable, but not enough.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-wm0-f69.google.com (mail-wm0-f69.google.com [74.125.82.69])
	by kanga.kvack.org (Postfix) with ESMTP id 7E35F6B0005
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 04:00:39 -0500 (EST)
Received: by mail-wm0-f69.google.com with SMTP id d63so1864354wma.4
        for <linux-mm@kvack.org>; Wed, 31 Jan 2018 01:00:39 -0800 (PST)
Received: from mx2.suse.de (mx2.suse.de. [195.135.220.15])
        by mx.google.com with ESMTPS id e191si10731167wme.159.2018.01.31.01.00.38
        for <linux-mm@kvack.org>
        (version=TLS1 cipher=AES128-SHA bits=128/128);
        Wed, 31 Jan 2018 01:00:38 -0800 (PST)
Date: Wed, 31 Jan 2018 10:00:37 +0100
From: Michal Hocko <mhocko@kernel.org>
Subject: Re: [LSF/MM TOPIC] mm documentation
Message-ID: <20180131090037.GQ21609@dhcp22.suse.cz>
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx>
 <20180130134141.GD21609@dhcp22.suse.cz>
 <20180130142849.GD21333@rapoport-lnx>
 <20180131023838.GA28275@bombadil.infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180131023838.GA28275@bombadil.infradead.org>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Matthew Wilcox <willy@infradead.org>
Cc: Mike Rapoport <rppt@linux.vnet.ibm.com>, lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue 30-01-18 18:38:38, Matthew Wilcox wrote:
> On Tue, Jan 30, 2018 at 04:28:50PM +0200, Mike Rapoport wrote:
> > On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
> > > It is good to hear that at least something has a documentation coverage.
> > > I was asking mostly because I _think_ that the API documentation is far
> > > from the top priority. 
> > 
> > API documentations is important for kernel developers who are not deeply
> > involved with mm. When one develops a device driver, knowing how to
> > allocate and free memory is essential. And, while *malloc are included in
> > kernel-api.rst, CMA and HMM documentation is not visible.
> > 
> > > We are seriously lacking any highlevel one which describes the design and
> > > subsytems interaction.
> > 
> > I should have describe it better, but by "creating a new structure for mm
> > documentation" I've also meant adding high level description.
> 
> We should be really clear what kind of documentation we're trying to create.
> 
> There are four distinct types of documentation which would be useful:
> 
>  - How, when and why to use the various function calls and their
>    parameters from the perspective of a user outside the mm/ hierarchy.
>    Device driver authors, filesystem authors and others of their ilk.
>  - The overall philosophy and structure of the mm directory, what it does,
>    why it does it, perhaps even outlines of abandoned approaches.
>  - What functionality the mm subsystem requires from others.  For example,
>    what does the mm rely on from the CPU architectures (and maybe it would
>    make sense to also include services the mm layer provides to arches in
>    this section, like setting up sparsemem).

yes

>  - How to tweak the various knobs that the mm subsystem provides.
>    Maybe this is all adequately documented elsewhere already.

This would be Documentation/sysctl/vm.txt which is one that is at least
close to be complete.
 
> Perhaps others can think of other types of documentation which would
> be useful.

- design documentation of various parts of the MM - reclaim, memory
  hotplug, memcg, page allocator, memory models, THP, rmap code (you
  name it)

> That shouldn't detract from my main point, which is that
> saying "Now we have mm documentation" is laudable, but not enough.

Absolutely agreed.

-- 
Michal Hocko
SUSE Labs

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-qt0-f197.google.com (mail-qt0-f197.google.com [209.85.216.197])
	by kanga.kvack.org (Postfix) with ESMTP id D13706B0009
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 05:56:17 -0500 (EST)
Received: by mail-qt0-f197.google.com with SMTP id c12so13798448qtj.3
        for <linux-mm@kvack.org>; Wed, 31 Jan 2018 02:56:17 -0800 (PST)
Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com. [148.163.156.1])
        by mx.google.com with ESMTPS id 1si4188606qkk.220.2018.01.31.02.56.16
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Wed, 31 Jan 2018 02:56:17 -0800 (PST)
Received: from pps.filterd (m0098393.ppops.net [127.0.0.1])
	by mx0a-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w0VAsO3r107559
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 05:56:16 -0500
Received: from e06smtp12.uk.ibm.com (e06smtp12.uk.ibm.com [195.75.94.108])
	by mx0a-001b2d01.pphosted.com with ESMTP id 2fuccm085n-1
	(version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT)
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 05:56:12 -0500
Received: from localhost
	by e06smtp12.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted
	for <linux-mm@kvack.org> from <rppt@linux.vnet.ibm.com>;
	Wed, 31 Jan 2018 10:56:09 -0000
Date: Wed, 31 Jan 2018 12:56:04 +0200
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx>
 <20180130134141.GD21609@dhcp22.suse.cz>
 <20180130142849.GD21333@rapoport-lnx>
 <8e8353c2-f985-2da0-d880-25992097cbf6@infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <8e8353c2-f985-2da0-d880-25992097cbf6@infradead.org>
Message-Id: <20180131105604.GA20535@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: Michal Hocko <mhocko@kernel.org>, lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Tue, Jan 30, 2018 at 09:32:04AM -0800, Randy Dunlap wrote:
> On 01/30/2018 06:28 AM, Mike Rapoport wrote:
> > On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
> >> On Tue 30-01-18 14:54:44, Mike Rapoport wrote:
> >>> On Tue, Jan 30, 2018 at 12:50:55PM +0100, Michal Hocko wrote:
> >>>> On Tue 30-01-18 12:54:50, Mike Rapoport wrote:
> >>>>> (forgot to CC linux-mm)
> >>>>>
> >>>>> On Tue, Jan 30, 2018 at 12:52:37PM +0200, Mike Rapoport wrote:
> >>>>>> Hello,
> >>>>>>
> >>>>>> The mm kernel-doc documentation is not in a great shape. 
> >>>>>>
> >>>>>> Some of the existing kernel-doc annotations were not reformatted during
> >>>>>> transition from dockbook to sphix. Sometimes the parameter descriptions
> >>>>>> do not match actual code. But aside these rather mechanical issues there
> >>>>>> are several points it'd like to discuss:
> >>>>>>
> >>>>>> * Currently, only 14 files are linked to kernel-api.rst under "Memory
> >>>>>> Management in Linux" section. We have more than hundred files only in mm.
> >>>>>> Even the existing documentation is not generated when running "make
> >>>>>> htmldocs"
> >>>>
> >>>> Is this documentation anywhere close to be actually useful?
> >>>
> >>> Some parts are documented better, some worse. For instance, bootmem and
> >>> z3fold are covered not bad at all, but, say, huge_memory has no structured
> >>> comments at all. Roughly half of the files in mm/ have some documentation,
> >>> but I didn't yet read that all to say how much of it is actually useful.
> >>
> >> It is good to hear that at least something has a documentation coverage.
> >> I was asking mostly because I _think_ that the API documentation is far
> >> from the top priority. 
> > 
> > API documentations is important for kernel developers who are not deeply
> > involved with mm. When one develops a device driver, knowing how to
> > allocate and free memory is essential. And, while *malloc are included in
> > kernel-api.rst, CMA and HMM documentation is not visible.
> > 
> >> We are seriously lacking any highlevel one which describes the design and
> >> subsytems interaction.
> > 
> > I should have describe it better, but by "creating a new structure for mm
> > documentation" I've also meant adding high level description.
> > 
> >> Well, we have missed that train years ago. It will be really hard to catch up.
> > 
> > At least we can try.
> 
> Hi,
> I would move it all to a new mm.rst file.  That would be easier to maintain
> and also allow parallel building.

Agree. Could also be Documentation/vm/index.rst.
 
> -- 
> ~Randy
> 

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-yw0-f197.google.com (mail-yw0-f197.google.com [209.85.161.197])
	by kanga.kvack.org (Postfix) with ESMTP id D01646B0005
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 09:59:55 -0500 (EST)
Received: by mail-yw0-f197.google.com with SMTP id t63so13433151ywa.11
        for <linux-mm@kvack.org>; Wed, 31 Jan 2018 06:59:55 -0800 (PST)
Received: from mx0a-001b2d01.pphosted.com (mx0b-001b2d01.pphosted.com. [148.163.158.5])
        by mx.google.com with ESMTPS id c25si2531863qtc.109.2018.01.31.06.59.54
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Wed, 31 Jan 2018 06:59:54 -0800 (PST)
Received: from pps.filterd (m0098414.ppops.net [127.0.0.1])
	by mx0b-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w0VExm2p121461
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 09:59:54 -0500
Received: from e06smtp15.uk.ibm.com (e06smtp15.uk.ibm.com [195.75.94.111])
	by mx0b-001b2d01.pphosted.com with ESMTP id 2fud3ysa9f-1
	(version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT)
	for <linux-mm@kvack.org>; Wed, 31 Jan 2018 09:59:53 -0500
Received: from localhost
	by e06smtp15.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted
	for <linux-mm@kvack.org> from <rppt@linux.vnet.ibm.com>;
	Wed, 31 Jan 2018 14:59:50 -0000
Date: Wed, 31 Jan 2018 16:59:46 +0200
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
References: <20180130105237.GB7201@rapoport-lnx>
 <20180130105450.GC7201@rapoport-lnx>
 <20180130115055.GZ21609@dhcp22.suse.cz>
 <20180130125443.GA21333@rapoport-lnx>
 <20180130134141.GD21609@dhcp22.suse.cz>
 <20180130142849.GD21333@rapoport-lnx>
 <20180131023838.GA28275@bombadil.infradead.org>
 <20180131090037.GQ21609@dhcp22.suse.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180131090037.GQ21609@dhcp22.suse.cz>
Message-Id: <20180131145945.GB20535@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: Michal Hocko <mhocko@kernel.org>
Cc: Matthew Wilcox <willy@infradead.org>, lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org

On Wed, Jan 31, 2018 at 10:00:37AM +0100, Michal Hocko wrote:
> On Tue 30-01-18 18:38:38, Matthew Wilcox wrote:
> > On Tue, Jan 30, 2018 at 04:28:50PM +0200, Mike Rapoport wrote:
> > > On Tue, Jan 30, 2018 at 02:41:41PM +0100, Michal Hocko wrote:
> > > > It is good to hear that at least something has a documentation coverage.
> > > > I was asking mostly because I _think_ that the API documentation is far
> > > > from the top priority. 
> > > 
> > > API documentations is important for kernel developers who are not deeply
> > > involved with mm. When one develops a device driver, knowing how to
> > > allocate and free memory is essential. And, while *malloc are included in
> > > kernel-api.rst, CMA and HMM documentation is not visible.
> > > 
> > > > We are seriously lacking any highlevel one which describes the design and
> > > > subsytems interaction.
> > > 
> > > I should have describe it better, but by "creating a new structure for mm
> > > documentation" I've also meant adding high level description.
> > 
> > We should be really clear what kind of documentation we're trying to create.
> > 
> > There are four distinct types of documentation which would be useful:
> > 
> >  - How, when and why to use the various function calls and their
> >    parameters from the perspective of a user outside the mm/ hierarchy.
> >    Device driver authors, filesystem authors and others of their ilk.
> >  - The overall philosophy and structure of the mm directory, what it does,
> >    why it does it, perhaps even outlines of abandoned approaches.
> >  - What functionality the mm subsystem requires from others.  For example,
> >    what does the mm rely on from the CPU architectures (and maybe it would
> >    make sense to also include services the mm layer provides to arches in
> >    this section, like setting up sparsemem).
> 
> yes
> 
> >  - How to tweak the various knobs that the mm subsystem provides.
> >    Maybe this is all adequately documented elsewhere already.
> 
> This would be Documentation/sysctl/vm.txt which is one that is at least
> close to be complete.
> 
> > Perhaps others can think of other types of documentation which would
> > be useful.
> 
> - design documentation of various parts of the MM - reclaim, memory
>   hotplug, memcg, page allocator, memory models, THP, rmap code (you
>   name it)
> 
> > That shouldn't detract from my main point, which is that
> > saying "Now we have mm documentation" is laudable, but not enough.
> 
> Absolutely agreed.

I don't think anybody is saying "we have mm documentation", at least in the
sense "mm is well documented".

One of my points was that bringing some order to the existing bits of the
documentation is an important step forward and it does not contradict
necessity to add documentation you and Matthew described here.

> -- 
> Michal Hocko
> SUSE Labs
> 
> --
> To unsubscribe, send a message with 'unsubscribe linux-mm' in
> the body to majordomo@kvack.org.  For more info on Linux MM,
> see: http://www.linux-mm.org/ .
> Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>
> 

-- 
Sincerely yours,
Mike.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <owner-linux-mm@kvack.org>
Received: from mail-pl1-f200.google.com (mail-pl1-f200.google.com [209.85.214.200])
	by kanga.kvack.org (Postfix) with ESMTP id 88D618E0001
	for <linux-mm@kvack.org>; Mon, 28 Jan 2019 02:04:32 -0500 (EST)
Received: by mail-pl1-f200.google.com with SMTP id v11so11216779ply.4
        for <linux-mm@kvack.org>; Sun, 27 Jan 2019 23:04:32 -0800 (PST)
Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com. [148.163.156.1])
        by mx.google.com with ESMTPS id d8si8009638plo.196.2019.01.27.23.04.31
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Sun, 27 Jan 2019 23:04:31 -0800 (PST)
Received: from pps.filterd (m0098399.ppops.net [127.0.0.1])
	by mx0a-001b2d01.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x0S73i0G080115
	for <linux-mm@kvack.org>; Mon, 28 Jan 2019 02:04:30 -0500
Received: from e06smtp05.uk.ibm.com (e06smtp05.uk.ibm.com [195.75.94.101])
	by mx0a-001b2d01.pphosted.com with ESMTP id 2q9u01m2ge-1
	(version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT)
	for <linux-mm@kvack.org>; Mon, 28 Jan 2019 02:04:30 -0500
Received: from localhost
	by e06smtp05.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted
	for <linux-mm@kvack.org> from <rppt@linux.ibm.com>;
	Mon, 28 Jan 2019 07:04:28 -0000
Date: Mon, 28 Jan 2019 09:04:22 +0200
From: Mike Rapoport <rppt@linux.ibm.com>
Subject: [LSF/MM TOPIC]: mm documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Message-Id: <20190128070421.GA2470@rapoport-lnx>
Sender: owner-linux-mm@kvack.org
List-ID: <linux-mm.kvack.org>
To: lsf-pc@lists.linux-foundation.org
Cc: linux-mm@kvack.org

Hi,

At the last Plumbers plenary there was a discussion about the
documentation and one of the questions to the panel was "Is it better
to have outdated documentation or no documentation at all?" And, not
surprisingly, they've answered, "No documentation is better than
outdated".

The mm documentation is, well, not entirely up to date. We can opt for
dropping the outdated parts, which would generate a nice negative
diffstat, but identifying the outdated documentation requires nearly
as much effort as updating it, so I think that making and keeping
the docs up to date would be a better option.

I'd like to discuss what can be done process-wise to improve the
situation.

Some points I had in mind:

* Pay more attention to docs during review
* Set an expectation level for docs accompanying a changeset
* Add automation to aid spotting inconsistencies between the code and
  the docs
* Spend some cycles to review and update the existing docs
* Spend some more cycles to add new documentation

I'd appreciate a discussion about how we can get to the second edition
of "Understanding the Linux Virtual Memory Manager", what are the gaps
(although they are too many), and what would be the best way to close
these gaps.

-- 
Sincerely yours,
Mike.

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <SRS0=SgWF=Q5=kvack.org=owner-linux-mm@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-1.0 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS,
	MAILING_LIST_MULTI,SPF_PASS autolearn=ham autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id A103AC43381
	for <linux-mm@archiver.kernel.org>; Fri, 22 Feb 2019 13:59:39 +0000 (UTC)
Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17])
	by mail.kernel.org (Postfix) with ESMTP id 5EE982075A
	for <linux-mm@archiver.kernel.org>; Fri, 22 Feb 2019 13:59:39 +0000 (UTC)
DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 5EE982075A
Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=huawei.com
Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix)
	id ECDDC8E010C; Fri, 22 Feb 2019 08:59:38 -0500 (EST)
Received: by kanga.kvack.org (Postfix, from userid 40)
	id E7EDD8E0109; Fri, 22 Feb 2019 08:59:38 -0500 (EST)
X-Delivered-To: int-list-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix, from userid 63042)
	id D940F8E010C; Fri, 22 Feb 2019 08:59:38 -0500 (EST)
X-Delivered-To: linux-mm@kvack.org
Received: from mail-ua1-f70.google.com (mail-ua1-f70.google.com [209.85.222.70])
	by kanga.kvack.org (Postfix) with ESMTP id AEE388E0109
	for <linux-mm@kvack.org>; Fri, 22 Feb 2019 08:59:38 -0500 (EST)
Received: by mail-ua1-f70.google.com with SMTP id g10so652092uan.2
        for <linux-mm@kvack.org>; Fri, 22 Feb 2019 05:59:38 -0800 (PST)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-original-authentication-results:x-gm-message-state:date:from:to
         :cc:subject:message-id:in-reply-to:references:organization
         :mime-version:content-transfer-encoding;
        bh=HrfXKKXiTUZHq6RqizgvYdNg5kks1CArbC2sBZOnnMg=;
        b=VIu1WiLLMWw5gvbqRfB2Gs/J+JOkaauxxxIKYAqrpcLee44xHhlvfOhW1FYzIYaPlO
         PwPlkk0ltUyxiVIu5m+gFjMlxv0GbD5UZsY2Nf89dltzWbYZ7hQNd3fpB6oiOZf1c6vE
         7nJ5ulmLDdJfSEpw/y0znKiUoGRaBzlwE/8l0TTyJe/zo2F60YmD8ybFAS8w3i0NLolp
         KuEXTYp6GacgpO50UOTaJNddZ0EtIM8BUcP+IPyjT3EPo/rFzKEnVnEOpS3acdK6Pctz
         DyrnwbOajLK4pU6oVRxkCIZWuOPUWELXvAyA9kcf6xgOVrcfPRa9ZnPKRJ2T+mQoqVrd
         lw+g==
X-Original-Authentication-Results: mx.google.com;       spf=pass (google.com: domain of jonathan.cameron@huawei.com designates 45.249.212.190 as permitted sender) smtp.mailfrom=jonathan.cameron@huawei.com
X-Gm-Message-State: AHQUAuYjIu3E0+QUYjqGRjw/98t8F5Yh3173T8RBq/b67r7jpZAGACKH
	VY5R0BBwZSA03ITBq9lPYiUGqHecnU0p2WgO5C2SGjIlX/ftS/umRmD/eFVT+lF/ldDURtKKGME
	vXaVK99ibZ3sWrejzIKVmIhrohJQG7pkGfjFnHj9f/puJAZwQvpvjmbGBvRhFYMP2kg==
X-Received: by 2002:a67:330f:: with SMTP id z15mr2242604vsz.9.1550843978403;
        Fri, 22 Feb 2019 05:59:38 -0800 (PST)
X-Google-Smtp-Source: AHgI3IaN8nmaaWF0wuy7s4QI+jBTJq2NkQg2bL4mvK+HpQeGK4IZZbj5FLaxEvPwr0oGo9qGAZ3K
X-Received: by 2002:a67:330f:: with SMTP id z15mr2242575vsz.9.1550843977605;
        Fri, 22 Feb 2019 05:59:37 -0800 (PST)
ARC-Seal: i=1; a=rsa-sha256; t=1550843977; cv=none;
        d=google.com; s=arc-20160816;
        b=OBbqe2j9tk6lhOLwfH5H7MZQZTzpdKPhbLR+N3W/RszeRiPcw0e09KpWaGDF8YphRM
         MF5oNnzaaITXg0Yc/t1ZGT03rT0PR5xW4FbE99+fv9oOrUvdVh+tEHfSSEi4r6AA2rJC
         JFjPNHev/CIOBcv3SvsFvT+naLgKSDZsNLQfgQ2aGXjr1XJ1s4D6XkEXiITMHDLtC9Do
         9WITcwyO4ffLF0h2QSLV0LcrhefVmsl/ZLu+5GetPMPsf5tKC947VrGSa7GGmTIR5ugR
         /ZW1ggxA8IqZayPNoyNY1ftgy7N+SyyC5TBtfPyt0MiNYmJp5sMDOkHALoVXtEZtAEpz
         ctXg==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816;
        h=content-transfer-encoding:mime-version:organization:references
         :in-reply-to:message-id:subject:cc:to:from:date;
        bh=HrfXKKXiTUZHq6RqizgvYdNg5kks1CArbC2sBZOnnMg=;
        b=zlNgOtzqPi3WHM2mZVIh/DzeCLgiD06dORKPL2d6mNeXVz9Z2TEjm7/Sxb471UKfIO
         r5wrql1Fu+/Jux6jaBZWKf7rCm0fXHlM4P2Hr8IUdN22BPfoI7RyRdBcLG5hSTx45t70
         HGRZCNQ8mdL7OCinfGdWbacva6Yax0LTUKwiElvjVLUmHAoPCZAaVMNHUUGFHXamwR65
         /phuvY/Tb7U77rUonGqdixsfs07TQzEYPuhnImJenE8DjA+/cb75j7H9srCYx4k5L6QD
         W9C/todYOTRsWPSRX1F8LsBApp11clQAxfpQbEfjYz3VLSdlK5MPZnrrwN6VEqHcsjAE
         2KkQ==
ARC-Authentication-Results: i=1; mx.google.com;
       spf=pass (google.com: domain of jonathan.cameron@huawei.com designates 45.249.212.190 as permitted sender) smtp.mailfrom=jonathan.cameron@huawei.com
Received: from huawei.com (szxga04-in.huawei.com. [45.249.212.190])
        by mx.google.com with ESMTPS id g133si714782vsd.297.2019.02.22.05.59.37
        for <linux-mm@kvack.org>
        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
        Fri, 22 Feb 2019 05:59:37 -0800 (PST)
Received-SPF: pass (google.com: domain of jonathan.cameron@huawei.com designates 45.249.212.190 as permitted sender) client-ip=45.249.212.190;
Authentication-Results: mx.google.com;
       spf=pass (google.com: domain of jonathan.cameron@huawei.com designates 45.249.212.190 as permitted sender) smtp.mailfrom=jonathan.cameron@huawei.com
Received: from DGGEMS410-HUB.china.huawei.com (unknown [172.30.72.58])
	by Forcepoint Email with ESMTP id 14334D59F46AF89BE186;
	Fri, 22 Feb 2019 21:59:32 +0800 (CST)
Received: from localhost (10.47.85.38) by DGGEMS410-HUB.china.huawei.com
 (10.3.19.210) with Microsoft SMTP Server id 14.3.408.0; Fri, 22 Feb 2019
 21:59:26 +0800
Date: Fri, 22 Feb 2019 13:59:18 +0000
From: Jonathan Cameron <jonathan.cameron@huawei.com>
To: Mike Rapoport <rppt@linux.ibm.com>
CC: <lsf-pc@lists.linux-foundation.org>, <linux-mm@kvack.org>
Subject: Re: [LSF/MM TOPIC]: mm documentation
Message-ID: <20190222135918.00000486@huawei.com>
In-Reply-To: <20190128070421.GA2470@rapoport-lnx>
References: <20190128070421.GA2470@rapoport-lnx>
Organization: Huawei
X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; i686-w64-mingw32)
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit
X-Originating-IP: [10.47.85.38]
X-CFilter-Loop: Reflected
X-Bogosity: Ham, tests=bogofilter, spamicity=0.000353, version=1.2.4
Sender: owner-linux-mm@kvack.org
Precedence: bulk
X-Loop: owner-majordomo@kvack.org
List-ID: <linux-mm.kvack.org>

On Mon, 28 Jan 2019 09:04:22 +0200
Mike Rapoport <rppt@linux.ibm.com> wrote:

> Hi,
> 
> At the last Plumbers plenary there was a discussion about the
> documentation and one of the questions to the panel was "Is it better
> to have outdated documentation or no documentation at all?" And, not
> surprisingly, they've answered, "No documentation is better than
> outdated".
> 
> The mm documentation is, well, not entirely up to date. We can opt for
> dropping the outdated parts, which would generate a nice negative
> diffstat, but identifying the outdated documentation requires nearly
> as much effort as updating it, so I think that making and keeping
> the docs up to date would be a better option.
> 
> I'd like to discuss what can be done process-wise to improve the
> situation.
> 
> Some points I had in mind:
> 
> * Pay more attention to docs during review
> * Set an expectation level for docs accompanying a changeset
> * Add automation to aid spotting inconsistencies between the code and
>   the docs
> * Spend some cycles to review and update the existing docs
> * Spend some more cycles to add new documentation
> 
> I'd appreciate a discussion about how we can get to the second edition
> of "Understanding the Linux Virtual Memory Manager", what are the gaps
> (although they are too many), and what would be the best way to close
> these gaps.
> 

As a recent newbie in mm code...

Even though it is perhaps in need of a refresh the existence of that
book is still useful and a great deal better than many other areas
of the kernel.  I would love to see a new version, but can fully
appreciate the immense effort involved.

Jonathan


From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <SRS0=z6PN=KP=kvack.org=owner-linux-mm@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-6.4 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH,
	DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_HELO_NONE,
	SPF_PASS autolearn=no autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 1606EC433B4
	for <linux-mm@archiver.kernel.org>; Thu, 20 May 2021 08:56:18 +0000 (UTC)
Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17])
	by mail.kernel.org (Postfix) with ESMTP id C651E610CB
	for <linux-mm@archiver.kernel.org>; Thu, 20 May 2021 08:56:17 +0000 (UTC)
DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C651E610CB
Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org
Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix)
	id 599528D000C; Thu, 20 May 2021 04:56:17 -0400 (EDT)
Received: by kanga.kvack.org (Postfix, from userid 40)
	id 54AC88D0001; Thu, 20 May 2021 04:56:17 -0400 (EDT)
X-Delivered-To: int-list-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix, from userid 63042)
	id 3EB5B8D000C; Thu, 20 May 2021 04:56:17 -0400 (EDT)
X-Delivered-To: linux-mm@kvack.org
Received: from forelay.hostedemail.com (smtprelay0238.hostedemail.com [216.40.44.238])
	by kanga.kvack.org (Postfix) with ESMTP id 0DC948D0001
	for <linux-mm@kvack.org>; Thu, 20 May 2021 04:56:17 -0400 (EDT)
Received: from smtpin09.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251])
	by forelay04.hostedemail.com (Postfix) with ESMTP id ABDA3B285
	for <linux-mm@kvack.org>; Thu, 20 May 2021 08:56:16 +0000 (UTC)
X-FDA: 78161002752.09.2DB2A75
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by imf24.hostedemail.com (Postfix) with ESMTP id B834AA0003A7
	for <linux-mm@kvack.org>; Thu, 20 May 2021 08:56:14 +0000 (UTC)
Received: by mail.kernel.org (Postfix) with ESMTPSA id 5C13861244;
	Thu, 20 May 2021 08:56:14 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org;
	s=k20201202; t=1621500975;
	bh=sgLeXevKuKXA8xR8O04AMUkeyWmeIurWrzzxunkxA1g=;
	h=Date:From:To:Cc:Subject:From;
	b=ke+M4LKy8aSmeJ1xDFikIICVfCWakj24spM5nA40+D93teITJPCKICsDksvxrAbpM
	 PcVToebo6TzMc/9juUVt6ud3b5RRptZQcxkz0ySOBNfhYB57QKs9EYkwh1J10ZCGwW
	 uAsda28Qa0QQ49bEBcG9oiM8DWBEOylaybC43JpxEdv/KkJ1OxG6LSkc659FiH6+mt
	 T+jYQaqN4U3Jp9Qdq6TCPZuRkK5y9TBV+f+FmJh4HwbsMUcXBLV45Qtv0Hd+HBH90g
	 R0m4A4dp912tfN7VsU5NOpvnOcLSzKPGMtRhunCfsTAcu+uxUMuIahFcAd7UBBWliK
	 j4aJARyTvw3Qw==
Date: Thu, 20 May 2021 11:56:09 +0300
From: Mike Rapoport <rppt@kernel.org>
To: lsf-pc@lists.linux-foundation.org
Cc: linux-mm@kvack.org
Subject: [LSF/MM TOPIC] mm documentation
Message-ID: <YKYkKTZsWZg88tWd@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
X-Rspamd-Queue-Id: B834AA0003A7
Authentication-Results: imf24.hostedemail.com;
	dkim=pass header.d=kernel.org header.s=k20201202 header.b=ke+M4LKy;
	dmarc=pass (policy=none) header.from=kernel.org;
	spf=pass (imf24.hostedemail.com: domain of rppt@kernel.org designates 198.145.29.99 as permitted sender) smtp.mailfrom=rppt@kernel.org
X-Rspamd-Server: rspam03
X-Stat-Signature: scr45wzokqspkpq5x4e747wskrrus96s
X-HE-Tag: 1621500974-723930
X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4
Sender: owner-linux-mm@kvack.org
Precedence: bulk
X-Loop: owner-majordomo@kvack.org
List-ID: <linux-mm.kvack.org>

Hi,

The mm documentation is, well, not entirely up to date. We can opt for
dropping the outdated parts, which would generate a nice negative
diffstat, but identifying the outdated documentation requires nearly
as much effort as updating it, so I think that making and keeping
the docs up to date would be a better option.

I'd like to discuss what can be done process-wise to improve the
situation.

Some points I had in mind:

* Pay more attention to docs during review
* Set an expectation level for docs accompanying a changeset
* Spend some cycles to review and update the existing docs
* Spend some more cycles to add new documentation
* Participate in prorams like Google Season of Docs

I'd appreciate a discussion about how we can improve the existing memory
management documentation so that a reader can get a coherent view of it,
what are the gaps (although they are too many), and what would be the best
way to close these gaps.

-- 
Sincerely yours,
Mike.


From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <SRS0=z6PN=KP=kvack.org=owner-linux-mm@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-3.6 required=3.0 tests=BAYES_00,DKIM_INVALID,
	DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE,
	SPF_PASS autolearn=no autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 4C9F8C433ED
	for <linux-mm@archiver.kernel.org>; Thu, 20 May 2021 14:19:41 +0000 (UTC)
Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17])
	by mail.kernel.org (Postfix) with ESMTP id CD78E61184
	for <linux-mm@archiver.kernel.org>; Thu, 20 May 2021 14:19:40 +0000 (UTC)
DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org CD78E61184
Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org
Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix)
	id 391F48E0015; Thu, 20 May 2021 10:19:40 -0400 (EDT)
Received: by kanga.kvack.org (Postfix, from userid 40)
	id 341D18E0012; Thu, 20 May 2021 10:19:40 -0400 (EDT)
X-Delivered-To: int-list-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix, from userid 63042)
	id 231898E0015; Thu, 20 May 2021 10:19:40 -0400 (EDT)
X-Delivered-To: linux-mm@kvack.org
Received: from forelay.hostedemail.com (smtprelay0145.hostedemail.com [216.40.44.145])
	by kanga.kvack.org (Postfix) with ESMTP id E49A28E0012
	for <linux-mm@kvack.org>; Thu, 20 May 2021 10:19:39 -0400 (EDT)
Received: from smtpin16.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251])
	by forelay05.hostedemail.com (Postfix) with ESMTP id 5C914181AC9B6
	for <linux-mm@kvack.org>; Thu, 20 May 2021 14:19:39 +0000 (UTC)
X-FDA: 78161817678.16.76505B0
Received: from casper.infradead.org (casper.infradead.org [90.155.50.34])
	by imf22.hostedemail.com (Postfix) with ESMTP id ECC78C0042FA
	for <linux-mm@kvack.org>; Thu, 20 May 2021 14:19:36 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed;
	d=infradead.org; s=casper.20170209; h=In-Reply-To:Content-Type:MIME-Version:
	References:Message-ID:Subject:Cc:To:From:Date:Sender:Reply-To:
	Content-Transfer-Encoding:Content-ID:Content-Description;
	bh=oC+YhFNmJbcV9OnbQ7S+PxXNJwDoQxAUyDbiKmv2pIM=; b=Ef5sESQQR+NtPb3uIxi3Z2ocWA
	sWRgujDSw8NIHGu/Pic5uM+fWLOkJ1KhxC9zmzwBbo589B4S+ZzB618KRKMGXi2gS1s4uscCdR88d
	pEKTFvl48ET7UKru2sMjIa6wwQyQUNd/foqDO8b3bC53RkRYBnMBAnNk7gcQUWSAWL+99uerWEqzg
	TTDrcgSakfK0L4ld5n3rflMxoYoryvlc6y/guURqRQdc+5zASQAPDM6DO3+xQbSek35Y+sX+q46vL
	Cm4uBASLPL5UkeoHnWS0X00fRlArMdoYsZjHg6OjQ4zoKHSmyeWJ6mzORpjh13cJm/BFRCxmWVorQ
	/LZxIdvg==;
Received: from willy by casper.infradead.org with local (Exim 4.94 #2 (Red Hat Linux))
	id 1ljjW0-00G7jU-3I; Thu, 20 May 2021 14:19:14 +0000
Date: Thu, 20 May 2021 15:19:08 +0100
From: Matthew Wilcox <willy@infradead.org>
To: Mike Rapoport <rppt@kernel.org>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org
Subject: Re: [LSF/MM TOPIC] mm documentation
Message-ID: <YKZv3CUcfx+qBCPw@casper.infradead.org>
References: <YKYkKTZsWZg88tWd@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <YKYkKTZsWZg88tWd@kernel.org>
X-Rspamd-Queue-Id: ECC78C0042FA
Authentication-Results: imf22.hostedemail.com;
	dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=Ef5sESQQ;
	spf=none (imf22.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org;
	dmarc=none
X-Rspamd-Server: rspam04
X-Stat-Signature: dtkyafkst6qu3wy63pjcd8ze8kq96c4d
X-HE-Tag: 1621520376-660898
X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4
Sender: owner-linux-mm@kvack.org
Precedence: bulk
X-Loop: owner-majordomo@kvack.org
List-ID: <linux-mm.kvack.org>

On Thu, May 20, 2021 at 11:56:09AM +0300, Mike Rapoport wrote:
> The mm documentation is, well, not entirely up to date. We can opt for
> dropping the outdated parts, which would generate a nice negative
> diffstat, but identifying the outdated documentation requires nearly
> as much effort as updating it, so I think that making and keeping
> the docs up to date would be a better option.
> 
> I'd like to discuss what can be done process-wise to improve the
> situation.
> 
> Some points I had in mind:
> 
> * Pay more attention to docs during review
> * Set an expectation level for docs accompanying a changeset
> * Spend some cycles to review and update the existing docs
> * Spend some more cycles to add new documentation
> * Participate in prorams like Google Season of Docs
> 
> I'd appreciate a discussion about how we can improve the existing memory
> management documentation so that a reader can get a coherent view of it,
> what are the gaps (although they are too many), and what would be the best
> way to close these gaps.

I think we have four target audiences for mm documentation,

 - Sysadmins/user space programmers who are trying to make their system
   perform well.  They need documentation of the
   proc/sys/cmdline/... parameters that the MM pays attention to.
 - Kernel programmers who are not (and do not wish to be) MM developers.
   Filesystem developers, device driver developers, networking
   developers.  They need kernel-doc for our exported functions and
   advice for when to use and not use particular functions/flags.
 - Programmers who want to "get started" in the MM area.  They may or
   may not be familiar with Linux internals (perhaps they're moving from
   another kernel, perhaps their experience is with some other part
   of Linux; perhaps they have no experience at all).  I think these
   people are probably well served by Mel's book, even if it is a few
   years old now.
 - Each other.  The MM is huge these days, and I certainly don't
   understand how it all interacts with itself.  I think we actually do
   a pretty good job of talking to each other and writing commit messages.

I think it's really the second group where we do the worst job of
documentation, but I may be biased.  It's certainly where I'm focusing
my documentation efforts.


From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <SRS0=us07=KQ=kvack.org=owner-linux-mm@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-6.4 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH,
	DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_HELO_NONE,
	SPF_PASS autolearn=no autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id D00B9C433ED
	for <linux-mm@archiver.kernel.org>; Fri, 21 May 2021 08:36:20 +0000 (UTC)
Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17])
	by mail.kernel.org (Postfix) with ESMTP id 65EC461363
	for <linux-mm@archiver.kernel.org>; Fri, 21 May 2021 08:36:20 +0000 (UTC)
DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 65EC461363
Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org
Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix)
	id E9CB68E0026; Fri, 21 May 2021 04:36:19 -0400 (EDT)
Received: by kanga.kvack.org (Postfix, from userid 40)
	id E254C8E0022; Fri, 21 May 2021 04:36:19 -0400 (EDT)
X-Delivered-To: int-list-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix, from userid 63042)
	id CC64D8E0026; Fri, 21 May 2021 04:36:19 -0400 (EDT)
X-Delivered-To: linux-mm@kvack.org
Received: from forelay.hostedemail.com (smtprelay0182.hostedemail.com [216.40.44.182])
	by kanga.kvack.org (Postfix) with ESMTP id 981A18E0022
	for <linux-mm@kvack.org>; Fri, 21 May 2021 04:36:19 -0400 (EDT)
Received: from smtpin20.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251])
	by forelay02.hostedemail.com (Postfix) with ESMTP id 3056AC5A0
	for <linux-mm@kvack.org>; Fri, 21 May 2021 08:36:19 +0000 (UTC)
X-FDA: 78164581278.20.BF6FF6E
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by imf03.hostedemail.com (Postfix) with ESMTP id 7529EC0042E7
	for <linux-mm@kvack.org>; Fri, 21 May 2021 08:36:16 +0000 (UTC)
Received: by mail.kernel.org (Postfix) with ESMTPSA id B539061057;
	Fri, 21 May 2021 08:36:16 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org;
	s=k20201202; t=1621586177;
	bh=WnbmDngFmIVGygLdgmAhgYLnaYcGhEuI/ubqB73Fn/Y=;
	h=Date:From:To:Cc:Subject:References:In-Reply-To:From;
	b=UklVLRejCZgJPSIPVE+1kclw/R8OoY2OEIk4PR2Ya9wjuMBNdwjnzoONYc0opWIur
	 AQlnDeyjzf3uVYKgquiqsa6FRUyp6hWGAEiBl1sBVHhMk155YLbzY9tuVtbNIHfe8c
	 sSbNfHdJuPrj95bML+4gmbPaDmGpg0BKssyX2yuTrUmWLfBJNUJ+WBhXsmdVMYdvDP
	 GtehouExfyP9110bpYYkUs8Ld/Bc9hEuut5OP1hP1Dzsz90eJ87TnclxMwjFtZE3Sa
	 y//fOe61QgAyPizsBvZn48FFdN1TASvA5fU11oDB7n0qnzPMjdbnl8ULGxzXNcF6uf
	 mhiVnimVTvEHg==
Date: Fri, 21 May 2021 11:36:11 +0300
From: Mike Rapoport <rppt@kernel.org>
To: Matthew Wilcox <willy@infradead.org>
Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org
Subject: Re: [LSF/MM TOPIC] mm documentation
Message-ID: <YKdw+5jW653ripVE@kernel.org>
References: <YKYkKTZsWZg88tWd@kernel.org>
 <YKZv3CUcfx+qBCPw@casper.infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <YKZv3CUcfx+qBCPw@casper.infradead.org>
Authentication-Results: imf03.hostedemail.com;
	dkim=pass header.d=kernel.org header.s=k20201202 header.b=UklVLRej;
	dmarc=pass (policy=none) header.from=kernel.org;
	spf=pass (imf03.hostedemail.com: domain of rppt@kernel.org designates 198.145.29.99 as permitted sender) smtp.mailfrom=rppt@kernel.org
X-Stat-Signature: dkpa69kszsgex3u999uzwmh1gri41det
X-Rspamd-Queue-Id: 7529EC0042E7
X-Rspamd-Server: rspam02
X-HE-Tag: 1621586176-268285
X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4
Sender: owner-linux-mm@kvack.org
Precedence: bulk
X-Loop: owner-majordomo@kvack.org
List-ID: <linux-mm.kvack.org>

On Thu, May 20, 2021 at 03:19:08PM +0100, Matthew Wilcox wrote:
> On Thu, May 20, 2021 at 11:56:09AM +0300, Mike Rapoport wrote:
> > The mm documentation is, well, not entirely up to date. We can opt for
> > dropping the outdated parts, which would generate a nice negative
> > diffstat, but identifying the outdated documentation requires nearly
> > as much effort as updating it, so I think that making and keeping
> > the docs up to date would be a better option.
> > 
> > I'd like to discuss what can be done process-wise to improve the
> > situation.
> > 
> > Some points I had in mind:
> > 
> > * Pay more attention to docs during review
> > * Set an expectation level for docs accompanying a changeset
> > * Spend some cycles to review and update the existing docs
> > * Spend some more cycles to add new documentation
> > * Participate in prorams like Google Season of Docs
> > 
> > I'd appreciate a discussion about how we can improve the existing memory
> > management documentation so that a reader can get a coherent view of it,
> > what are the gaps (although they are too many), and what would be the best
> > way to close these gaps.
> 
> I think we have four target audiences for mm documentation,
> 
>  - Sysadmins/user space programmers who are trying to make their system
>    perform well.  They need documentation of the
>    proc/sys/cmdline/... parameters that the MM pays attention to.

I'd say this part needs some love. Just a few weeks ago we've discussed how
/proc/meminfo description is outdated and there are more examples.
Besides, this is probably the most important part to keep up to date.

>  - Kernel programmers who are not (and do not wish to be) MM developers.
>    Filesystem developers, device driver developers, networking
>    developers.  They need kernel-doc for our exported functions and
>    advice for when to use and not use particular functions/flags.
>  - Programmers who want to "get started" in the MM area.  They may or
>    may not be familiar with Linux internals (perhaps they're moving from
>    another kernel, perhaps their experience is with some other part
>    of Linux; perhaps they have no experience at all).  I think these
>    people are probably well served by Mel's book, even if it is a few
>    years old now.

Mel's book is definitely an excellent starting point, but I afraid its age
is starting to show. As it was written mostly about 2.4 with some bits
about 2.6, there are lot of details that are missing in the book. Some are
probably less important because the concept didn't change much (e.g. page
table management), but others have considerable effect on our code (e.g
migration, compaction, THP).

>  - Each other.  The MM is huge these days, and I certainly don't
>    understand how it all interacts with itself.  I think we actually do
>    a pretty good job of talking to each other and writing commit messages.

IMHO, there is a fifth group: arch developers. I think it is important to
have documentation of what core mm expects from an architecture and what is
the expected semantics of various low level functions architectures supply.
 
> I think it's really the second group where we do the worst job of
> documentation, but I may be biased.  It's certainly where I'm focusing
> my documentation efforts.

I'm not sure it's the worst, but certainly along with the first group it's
the most important part.

-- 
Sincerely yours,
Mike.


From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <SRS0=aGFf=KU=kvack.org=owner-linux-mm@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-2.8 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,
	HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS
	autolearn=no autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 696F8C2B9F8
	for <linux-mm@archiver.kernel.org>; Tue, 25 May 2021 07:04:22 +0000 (UTC)
Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17])
	by mail.kernel.org (Postfix) with ESMTP id E597C6138C
	for <linux-mm@archiver.kernel.org>; Tue, 25 May 2021 07:04:21 +0000 (UTC)
DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E597C6138C
Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com
Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix)
	id 901706B006C; Tue, 25 May 2021 03:04:20 -0400 (EDT)
Received: by kanga.kvack.org (Postfix, from userid 40)
	id 8D0C26B006E; Tue, 25 May 2021 03:04:20 -0400 (EDT)
X-Delivered-To: int-list-linux-mm@kvack.org
Received: by kanga.kvack.org (Postfix, from userid 63042)
	id 440296B0070; Tue, 25 May 2021 03:04:20 -0400 (EDT)
X-Delivered-To: linux-mm@kvack.org
Received: from forelay.hostedemail.com (smtprelay0153.hostedemail.com [216.40.44.153])
	by kanga.kvack.org (Postfix) with ESMTP id 00F436B006C
	for <linux-mm@kvack.org>; Tue, 25 May 2021 03:04:19 -0400 (EDT)
Received: from smtpin18.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251])
	by forelay02.hostedemail.com (Postfix) with ESMTP id 74A946135
	for <linux-mm@kvack.org>; Tue, 25 May 2021 07:04:19 +0000 (UTC)
X-FDA: 78178864638.18.BD0CA37
Received: from mail-vs1-f53.google.com (mail-vs1-f53.google.com [209.85.217.53])
	by imf10.hostedemail.com (Postfix) with ESMTP id 8839440002FF
	for <linux-mm@kvack.org>; Tue, 25 May 2021 07:04:13 +0000 (UTC)
Received: by mail-vs1-f53.google.com with SMTP id f11so15549333vst.0
        for <linux-mm@kvack.org>; Tue, 25 May 2021 00:04:19 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20161025;
        h=mime-version:references:in-reply-to:from:date:message-id:subject:to
         :cc;
        bh=R5qSYI3H+0hKhtur4WubbZFIAqp8tvqJ+a69rLE2/4c=;
        b=WQXhVd5gnXzCoc3weXSpAu24OZHy68JLoNxpB5SQKazPhOmji1Bo6tceB2begnrEg7
         yaKjP4Zk82rmO74yXO0dObcMUvgF83eNzWLR5eOZOO4GkzCMBr1JEMqZf2AqqLQIT9Rd
         M4Ii/CKo6pE+Nyp6ML3UgyguHvMcHiD9imOitKs2yjkMpLYRIckqRHYipPwIrgopDqFZ
         Bv+Du75r4rBpIMmSRpmwNsHPEYLp3q+GDettVjehiVeTnDwwMyD/AAC9jyrLlZQ/MGQE
         dv42BlJwljANRACo27G73zpGSKJPWuIBQZi4fJVA1tn32bHuIMlhOEdnpcePZZZPfqaQ
         67xw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20161025;
        h=x-gm-message-state:mime-version:references:in-reply-to:from:date
         :message-id:subject:to:cc;
        bh=R5qSYI3H+0hKhtur4WubbZFIAqp8tvqJ+a69rLE2/4c=;
        b=eDAE+wbHMWXianVPxoRnDCHTLnZd8QhU10jTdarKuIKiVj2l0/rKQFOOeD7bEqD8Rj
         zzVb4c6gfGmtIQNBreWK2Hccmlmi6LtfVIflZzXmMZki1xCbayO3XQxjvXrE5A4P5T67
         x2Yow2O06EimYMdWAlX1QwCYQGSAs1QdRKj3KSzyI45DmqcIayBiJoB9CyztA/Z6rs64
         WdvigjXnny6ug4XMH3cKesf15mFxd5S/Gd7DpgySB55VBB/5eljx8pAX0OUHNDNhYgEo
         rz96ksbMgE0V/3ckyPcgkNE7KmpOtMge9hE+QAnXFhq28UKsIzT5uDb/L5c48hVsdvhk
         oNYw==
X-Gm-Message-State: AOAM530CrHOeNG9Q+fvFQrQb6rSwE1NRFSbDndCZPxA+c1+DOKmj2h6G
	ovRlp/pQh7eYN9uKa9CIi4kXO0TTiWuOvOaBqYA=
X-Google-Smtp-Source: ABdhPJxmLCWS+KeqwHpEBEz+DpfNQsoageeB769AOSzYB1qjSvKBtvqwo57xCIPJW5357VwJkaG0297DdNPV4OMkfKM=
X-Received: by 2002:a67:7cc7:: with SMTP id x190mr21200522vsc.30.1621926258425;
 Tue, 25 May 2021 00:04:18 -0700 (PDT)
MIME-Version: 1.0
References: <YKYkKTZsWZg88tWd@kernel.org> <YKZv3CUcfx+qBCPw@casper.infradead.org>
 <YKdw+5jW653ripVE@kernel.org>
In-Reply-To: <YKdw+5jW653ripVE@kernel.org>
From: Souptick Joarder <jrdr.linux@gmail.com>
Date: Tue, 25 May 2021 12:34:06 +0530
Message-ID: <CAFqt6zbu4Q6uAjgFOk7-bx-CezvjcT0-x9018Kcaung-g2vkOQ@mail.gmail.com>
Subject: Re: [LSF/MM TOPIC] mm documentation
To: Mike Rapoport <rppt@kernel.org>
Cc: Matthew Wilcox <willy@infradead.org>, lsf-pc@lists.linux-foundation.org, 
	Linux-MM <linux-mm@kvack.org>
Content-Type: text/plain; charset="UTF-8"
Authentication-Results: imf10.hostedemail.com;
	dkim=pass header.d=gmail.com header.s=20161025 header.b=WQXhVd5g;
	dmarc=pass (policy=none) header.from=gmail.com;
	spf=pass (imf10.hostedemail.com: domain of jrdrlinux@gmail.com designates 209.85.217.53 as permitted sender) smtp.mailfrom=jrdrlinux@gmail.com
X-Stat-Signature: e7exj56mcykywe7hgizbftuodzu71oyb
X-Rspamd-Queue-Id: 8839440002FF
X-Rspamd-Server: rspam02
X-HE-Tag: 1621926253-228942
X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4
Sender: owner-linux-mm@kvack.org
Precedence: bulk
X-Loop: owner-majordomo@kvack.org
List-ID: <linux-mm.kvack.org>

On Fri, May 21, 2021 at 2:06 PM Mike Rapoport <rppt@kernel.org> wrote:
>
> On Thu, May 20, 2021 at 03:19:08PM +0100, Matthew Wilcox wrote:
> > On Thu, May 20, 2021 at 11:56:09AM +0300, Mike Rapoport wrote:
> > > The mm documentation is, well, not entirely up to date. We can opt for
> > > dropping the outdated parts, which would generate a nice negative
> > > diffstat, but identifying the outdated documentation requires nearly
> > > as much effort as updating it, so I think that making and keeping
> > > the docs up to date would be a better option.
> > >
> > > I'd like to discuss what can be done process-wise to improve the
> > > situation.
> > >
> > > Some points I had in mind:
> > >
> > > * Pay more attention to docs during review
> > > * Set an expectation level for docs accompanying a changeset
> > > * Spend some cycles to review and update the existing docs
> > > * Spend some more cycles to add new documentation
> > > * Participate in prorams like Google Season of Docs
> > >
> > > I'd appreciate a discussion about how we can improve the existing memory
> > > management documentation so that a reader can get a coherent view of it,
> > > what are the gaps (although they are too many), and what would be the best
> > > way to close these gaps.
> >
> > I think we have four target audiences for mm documentation,
> >
> >  - Sysadmins/user space programmers who are trying to make their system
> >    perform well.  They need documentation of the
> >    proc/sys/cmdline/... parameters that the MM pays attention to.
>
> I'd say this part needs some love. Just a few weeks ago we've discussed how
> /proc/meminfo description is outdated and there are more examples.
> Besides, this is probably the most important part to keep up to date.
>
> >  - Kernel programmers who are not (and do not wish to be) MM developers.
> >    Filesystem developers, device driver developers, networking
> >    developers.  They need kernel-doc for our exported functions and
> >    advice for when to use and not use particular functions/flags.
> >  - Programmers who want to "get started" in the MM area.  They may or
> >    may not be familiar with Linux internals (perhaps they're moving from
> >    another kernel, perhaps their experience is with some other part
> >    of Linux; perhaps they have no experience at all).  I think these
> >    people are probably well served by Mel's book, even if it is a few
> >    years old now.
>
> Mel's book is definitely an excellent starting point, but I afraid its age
> is starting to show. As it was written mostly about 2.4 with some bits
> about 2.6, there are lot of details that are missing in the book. Some are
> probably less important because the concept didn't change much (e.g. page
> table management), but others have considerable effect on our code (e.g
> migration, compaction, THP).

IMO, updating Mel's book will be helpful. I thought about it but realized that
without guidance I can't make good progress.

>
> >  - Each other.  The MM is huge these days, and I certainly don't
> >    understand how it all interacts with itself.  I think we actually do
> >    a pretty good job of talking to each other and writing commit messages.
>
> IMHO, there is a fifth group: arch developers. I think it is important to
> have documentation of what core mm expects from an architecture and what is
> the expected semantics of various low level functions architectures supply.
>
> > I think it's really the second group where we do the worst job of
> > documentation, but I may be biased.  It's certainly where I'm focusing
> > my documentation efforts.
>
> I'm not sure it's the worst, but certainly along with the first group it's
> the most important part.

I am interested to contribute to this if agree to take it forward.