Re: [LSF/MM TOPIC] mm documentation

[Souptick Joarder <jrdr.linux@gmail.com>]

On Fri, May 21, 2021 at 2:06 PM Mike Rapoport <rppt@kernel.org> wrote:
>
> On Thu, May 20, 2021 at 03:19:08PM +0100, Matthew Wilcox wrote:
> > On Thu, May 20, 2021 at 11:56:09AM +0300, Mike Rapoport wrote:
> > > 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 prorams 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 think we have four target audiences for mm documentation,
> >
> >  - Sysadmins/user space programmers who are trying to make their system
> >    perform well.  They need documentation of the
> >    proc/sys/cmdline/... parameters that the MM pays attention to.
>
> I'd say this part needs some love. Just a few weeks ago we've discussed how
> /proc/meminfo description is outdated and there are more examples.
> Besides, this is probably the most important part to keep up to date.
>
> >  - Kernel programmers who are not (and do not wish to be) MM developers.
> >    Filesystem developers, device driver developers, networking
> >    developers.  They need kernel-doc for our exported functions and
> >    advice for when to use and not use particular functions/flags.
> >  - Programmers who want to "get started" in the MM area.  They may or
> >    may not be familiar with Linux internals (perhaps they're moving from
> >    another kernel, perhaps their experience is with some other part
> >    of Linux; perhaps they have no experience at all).  I think these
> >    people are probably well served by Mel's book, even if it is a few
> >    years old now.
>
> Mel's book is definitely an excellent starting point, but I afraid its age
> is starting to show. As it was written mostly about 2.4 with some bits
> about 2.6, there are lot of details that are missing in the book. Some are
> probably less important because the concept didn't change much (e.g. page
> table management), but others have considerable effect on our code (e.g
> migration, compaction, THP).

IMO, updating Mel's book will be helpful. I thought about it but realized that
without guidance I can't make good progress.

>
> >  - Each other.  The MM is huge these days, and I certainly don't
> >    understand how it all interacts with itself.  I think we actually do
> >    a pretty good job of talking to each other and writing commit messages.
>
> IMHO, there is a fifth group: arch developers. I think it is important to
> have documentation of what core mm expects from an architecture and what is
> the expected semantics of various low level functions architectures supply.
>
> > I think it's really the second group where we do the worst job of
> > documentation, but I may be biased.  It's certainly where I'm focusing
> > my documentation efforts.
>
> I'm not sure it's the worst, but certainly along with the first group it's
> the most important part.

I am interested to contribute to this if agree to take it forward.