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

[Mike Rapoport <rppt@kernel.org>]

On Sun, May 21, 2023 at 04:50:57PM -0700, David Rientjes wrote:
> On Tue, 16 May 2023, Jonathan Corbet wrote:
> 
> > >> > 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.
> > >> 
> > >> Yeah, this could be a good starting point actually, as rather than starting
> > >> from zero, people would have some material that they can cross-check.
> > >
> > > I'm going to suggest "MM docs" for the next Outreachy round and I'll ping
> > > you then about the "Convert Lorenzo's book to kernel documentation"
> > > project.
> > >
> > > As for participation in the Google Season of Docs, maybe this should be
> > > more broad than only mm docs.
> > > Jon, what do you think?
> > 
> > Sorry, I'm still catching up from travel and have a lot of digging out
> > to do...
> > 
> > Converting relevant bits of the book to RST seems like a great project.
> > In theory pandoc can do that, but I've never tried it and can imagine
> > that a fair amount of tweaking is required.
> > 
> > Season of docs definitely seems worth looking into, but we've missed the
> > bus for this year.  Something to keep in mind next January.
> > 
> 
> I think both of these programs are useful for importing mm documentation 
> that is up-to-date at the time that it's imported.
> 
> I'm concerned that the documentation will quickly become out of date, 
> however.  If mm documentation were imported before the introduction of 
> folios or per-vma locking, for example, it would likely need large scale 
> changes.

Well, yes and no. Willy did a decent job of updating the docs along with
the folio conversion and out of hundreds of commits only about 50 touch
Documentation/. I believe there are still some gaps, but I'd imaging they
are not that big.

With per-vma lock I believe there are some updates pending and if we had
more elaborate documentation it would have required more work, but still I
don't think it would have been something large scale, but rather
semi-mechanical replacement of mmap_lock mentions with vma lock and
updating a few paragraphs that actually described the locking.

But this is all theory of course :)
 
> Maybe the idea is that any documentation, no matter how outdated, is 
> better than no documentation.  This may not always be the case, however: 
> how often have people become frustrated that the documentation that does 
> exist doesn't actually reflect the current state of the kernel anymore?  

What we have now is Mel's book and some assorted pieces here and there, so
having more documentation seems really useful to me, even if it won't
always be up to date.

I agree with Lorenzo that the most important bits, like, for example,
general description of allocation, reclaim, compaction, won't require
frequent changes and I think it'll be manageable.
 
> Mike, I think one of the goals you were trying to achieve at LSF/MM/BPF 
> was how this documentation would not only get originally created/imported, 
> but also how it would stay relatively up-to-date.  To keep the 
> documentation current, I think the burden would likely need to fall on the 
> kernel hakcers who are actually developing the code?

The hackers and maintainers, yes. I believe that as a part of our process
we should pay more attention to documentation and ask contributors to
update the documentation along with the code. 
I personally do it for some time now, but unfortunately I can't always keep
up with the pace.

-- 
Sincerely yours,
Mike.