On Tue, 1 Feb 2022 at 11:03, Mike Rapoport <rppt@xxxxxxxxxx> 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). 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. >
