Re: [LSF/MM/BPF TOPIC] mm documentation

[Lorenzo Stoakes <lstoakes@gmail.com>]

On Tue, 1 Feb 2022 at 11:03, Mike Rapoport <rppt@kernel.org> wrote:
>
> Hi all,
>
> I'm suggesting this topic for a while now, maybe if we finally get to talk
> about it in person something will improve :)
>
> 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 programs 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've been thinking about this since the lsf/mm discussion and wonder
whether there might be some way I can contribute portions of the book
that _do_ overlap the aims of the mm documentation? Specifically those
parts which are descriptive, rather than the parts that are code
commentary (which I still consider to be inappropriate for, and
orthogonal to, the docs).

An example, as Mike pointed out on the relevant thread, is the diagram
I made for the vma merge cases [1]. I feel this is quite handy for
looking at this code and have used it a lot for my work in this area.
There are a number of parts of the book that seem relevant like this.

HOWEVER, there are some issues here:-

1. The book is pure LaTeX. Not sure how easy it would be to port any
part of it to the mm codebase.
2. I explicitly target v6 out of necessity. Therefore some
explanations are simply incorrect for $curr kernel, and others which
are accurate right now will be inaccurate as soon as Willy decides to
change them :)
3. I don't have the time to put in the effort to port changes to $curr
kernel, nor can I stand too much nitpicky review because that'll just
hold up the remaining book work.

So I wonder whether it would be helpful to provide parts of this work
'as is'? I am sure there are some diagrams at the very least I can
provide. I am happy to do so (and accept a GPL/whatever license for
those bits).

Also, as always, I am happy to send the current WIP book to anybody in
MAINTAINERS if they would like to take a look!

Relatedly, I am shortly going to be working on the page cache chapter,
Willy - I wondered if you would like to take a look when I am done
with that?

Cheers, Lorenzo

[1]:https://ljs.io/merge_cases.png

> --
> Sincerely yours,
> Mike.
>