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

[Mike Rapoport <rppt@kernel.org>]

On Thu, May 11, 2023 at 06:39:50PM -0700, Lorenzo Stoakes wrote:
> 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).

If you are comfortable with random people taking your work and adjusting it
to fit into Documentation/mm, I think there are a few ways to move this
forward without requiring you to do the actual work.

First, I'm ready to give it a try and see how much effort is required for
LaTeX to rst conversion and what are the changes that need to be made to
the content. Maybe others in the community would be able to contribute too.

Next, if people ask about entry level MM projects that's something that we
can suggest as well.

And if we are going to participate in projects like Outreachy and Google
Season of Docs, we can suggest a project "Convert Lorenzo's book to kernel
documentation" alongside "Write more MM documentation" project.
 
> 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.
> >

-- 
Sincerely yours,
Mike.