Re: [LSF/MM TOPIC] mm documentation

[Matthew Wilcox <willy@infradead.org>]

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.
 - 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.
 - 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.

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.