Re: [LSF/MM TOPIC]: mm documentation

[Jonathan Cameron <jonathan.cameron@huawei.com>]

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