: mm documentation
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.
Signature · 2 lines
Sincerely yours, Mike.
Quoted 26 lines · On Mon, 28 Jan 2019 09:04:22 +0200 Mike Rapoport <[email protected]> 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
Quoted 5 lines
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