On Mon, 28 Jan 2019 09:04:22 +0200 Mike Rapoport <rppt@xxxxxxxxxxxxx> wrote: > Hi, > > At the last Plumbers plenary there was a discussion about the > documentation and one of the questions to the panel was "Is it better > to have outdated documentation or no documentation at all?" And, not > surprisingly, they've answered, "No documentation is better than > outdated". > > 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 > * Add automation to aid spotting inconsistencies between the code and > the docs > * Spend some cycles to review and update the existing docs > * Spend some more cycles to add new documentation > > I'd appreciate a discussion about how we can get to the second edition > of "Understanding the Linux Virtual Memory Manager", what are the gaps > (although they are too many), and what would be the best way to close > these gaps. > As a recent newbie in mm code... Even though it is perhaps in need of a refresh the existence of that book is still useful and a great deal better than many other areas of the kernel. I would love to see a new version, but can fully appreciate the immense effort involved. Jonathan
