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

[David Rientjes <rientjes@google.com>]

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.

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?  

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?