Re: [PATCH 0/2] docs/mm: start filling out new structure

[Lorenzo Stoakes]

On Sun, Jan 01, 2023 at 11:45:21AM +0200, Mike Rapoport wrote:
> From: "Mike Rapoport (IBM)" <rppt@xxxxxxxxxx>
>
> Hi,
>
> Last year at LSF/MM Matthew promptly created the new structure for MM
> documentation, but there still was no patches with content.
>
> I've started to work on it a while ago and I wanted to send it out in a
> more complete form, but I've got distracted and didn't have time to work
> on this.
>
> With fast changes around struct page and the threat of Lorenzo's book,
> I've decided to send out what I have till now with a hope that we can
> really make this a collaborative effort with people filling paragraph
> here and there.

:))

Don't worry, I feel as if this documentation and my book only overlap partially,
so there is no reason to consider it a threat!

Being a developer I love bullet points. So I will sum up my thoughts on this
that way:-

- I have to, practically, target a single kernel version (v6.0) if I am to stand
  any chance of getting this done. By the time the book is released (mid 2024
  maybe even later?) it will have slid further from tip kernel so the aims of
  the documentation and the book naturally diverge on this basis alone.

- I have to, again for entirely pragmatic reasons, target a specific
  architecture (x86-64) where architecture-specific discussions are to be had,
  another luxury the core documents cannot afford, so in this respect they must
  go further and be broader than my own.

- The aims of the mm documentation here are, as I gather, to provide a broad
  overview, API guide, and general explainer. Of course the book will somewhat
  overlap with each of these, but I am also taking a deeply self-indulgent (and
  perhaps unwise) approach of going quite a bit deeper and diving into code and
  visualisations and providing something of a 'guided tour' of the kernel in a
  way that just wouldn't make sense or be probably particularly helpful in the
  context of mm docs.

- I feel as if the two are actually symbiotic rather than in competition and I
  really want both to happen and be helpful to people, coming from different
  angles and with different aims as they do. Given your and other maintainers's
  competence and experience both of which dramatically eclipse mine many, many
  times over I am certain these documents will be excellent and will be
  extremely useful, I only hope that the book can at least somewhat compare!

I'd like to contribute too but my time is so limited with the day job and book
that I'd rather keep what time I have for kernel contributions to code/reviews
in order to keep myself 'in the game' so to speak, however I am happy to review
when I have a moment to!

Proximally speaking, I will take a look at the actual patches here and try
(humbly!) to review as best I can!

I should add that I feel quite honoured to be referenced at all here! :)

Cheers, Lorenzo

>
> If somebody does not feel like sending formal patches, just send me the
> "raw" text my way and I'll deal with the rest.
>
> The text is relatively heavily formatted because I believe the target
> audience will prefer html version.
>
> Mike Rapoport (IBM) (2):
>   docs/mm: Page Reclaim: add page label to allow external references
>   docs/mm: Physical Memory: add structure, introduction and nodes
>     description
>
>  Documentation/mm/page_reclaim.rst    |   2 +
>  Documentation/mm/physical_memory.rst | 322 +++++++++++++++++++++++++++
>  2 files changed, 324 insertions(+)
>
> --
> 2.35.1
>