[PATCH 0/4] Docs/mm: rename legacy docs to unsorted docs

[PATCH 0/4] Docs/mm: rename legacy docs to unsorted docs

[SeongJae Park]

The work for changing the memory mangement documentation outline has
started from 2022.  For that, old documents have placed under new
chapter, "Legacy Documentations".  The plan is to eventually move all
old documentations into new outline, while asking new documents to be
added on the new outline from the beginning.

However, it is unclear where on the new outline each document should be
placed for some cases.  Meanwhile, the name ("legacy") makes readers
feel the documents under the chapter might be outdated or not actively
maintained.  The absence of clear criteria for new outline also makes
new documents difficult to find where those should be placed.  A new
document was put on the bottom of the new outline recently, apparently
not based on a clear guideline but just because it is the bottom of the
list.

Rename the "Legagy Documentation" chapter to "Unsorted Documentations"
with minor fixups.

SeongJae Park (4):
  Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter
  Docs/mm/index: Remove 'Memory Management Guide' chapter marker
  Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted
    Documentation'
  Docs/mm/index: move allocation profiling document to unsorted
    documents chapter

 Documentation/mm/allocation-profiling.rst |  1 -
 Documentation/mm/index.rst                | 19 ++++++++-----------
 2 files changed, 8 insertions(+), 12 deletions(-)


base-commit: 5dc709e59ba6486e519b22f86278c978b422a025
-- 
2.39.2

[PATCH 1/4] Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter

[SeongJae Park]

'Theory of operation' part of allocation-profiling document is
apparently a chapter.  However, it is mistakenly marked as a document
title.  As a result, rendered mm document index page shows two items for
the document.  Fix it to be marked as a chapter.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/allocation-profiling.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/mm/allocation-profiling.rst b/Documentation/mm/allocation-profiling.rst
index d3b733b41ae6..ffd6655b7be2 100644
--- a/Documentation/mm/allocation-profiling.rst
+++ b/Documentation/mm/allocation-profiling.rst
@@ -46,7 +46,6 @@ Example output::
          55M     4887 mm/slub.c:2259 func:alloc_slab_page
         122M    31168 mm/page_ext.c:270 func:alloc_page_ext
 
-===================
 Theory of operation
 ===================
 
-- 
2.39.2

Re: [PATCH 1/4] Docs/mm/allocation-profiling: mark 'Theory of operation' as chapter

[Suren Baghdasaryan]

On Mon, Jul 1, 2024 at 12:05 PM SeongJae Park <sj@kernel.org> wrote:
>
> 'Theory of operation' part of allocation-profiling document is
> apparently a chapter.  However, it is mistakenly marked as a document
> title.  As a result, rendered mm document index page shows two items for
> the document.  Fix it to be marked as a chapter.
>
> Signed-off-by: SeongJae Park <sj@kernel.org>

Acked-by: Suren Baghdasaryan <surenb@google.com>

> ---
>  Documentation/mm/allocation-profiling.rst | 1 -
>  1 file changed, 1 deletion(-)
>
> diff --git a/Documentation/mm/allocation-profiling.rst b/Documentation/mm/allocation-profiling.rst
> index d3b733b41ae6..ffd6655b7be2 100644
> --- a/Documentation/mm/allocation-profiling.rst
> +++ b/Documentation/mm/allocation-profiling.rst
> @@ -46,7 +46,6 @@ Example output::
>           55M     4887 mm/slub.c:2259 func:alloc_slab_page
>          122M    31168 mm/page_ext.c:270 func:alloc_page_ext
>
> -===================
>  Theory of operation
>  ===================
>
> --
> 2.39.2
>

[PATCH 2/4] Docs/mm/index: Remove 'Memory Management Guide' chapter marker

[SeongJae Park]

'Memory Management Guide' chapter aims to be not an additional chapter
of the document, but the ultimate single outline of the document.  In
the sense, marking it as a chapter under the document makes no sense,
and the rendered document looks odd.  Remove the chapter marker.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/index.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
index 48b9b559ca7b..5007815405f1 100644
--- a/Documentation/mm/index.rst
+++ b/Documentation/mm/index.rst
@@ -2,9 +2,6 @@
 Memory Management Documentation
 ===============================
 
-Memory Management Guide
-=======================
-
 This is a guide to understanding the memory management subsystem
 of Linux.  If you are looking for advice on simply allocating memory,
 see the :ref:`memory_allocation`.  For controlling and tuning guides,
-- 
2.39.2

[PATCH 3/4] Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted Documentation'

[SeongJae Park]

The intention of 'Legacy Documentation' chapter is to keep the old
documents that not yet sorted into the new outline, and encourage new
documents to be integrated in the new outline from the beginning.

However, the new outline will take some more time to be completed.  It
has started about two years ago, and still many parts are not yet
written.  Also, there is no clear guidline for placing each document for
all cases, for not only the 'legacy' documents, but also for new
documents.  For example, memory allocation profiling document has been
added to the bottom of the new outline.  Apparently it was not following
some well-defined guideliens or a result of a discussion.

Furthermore, the title ("legacy") makes people feel the documents on the
chapter might be outdated or not actively maintained.

Rename 'Legacy Documentation' to 'Unsorted Documentation' and remove the
description saying it is for 'older' documents.  After this change, new
documents that not clear enough where it should be placed on the new
outline can be added on the chapter while well-defined guidelines or
discussion for the new outline is made.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/index.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
index 5007815405f1..15614df2b989 100644
--- a/Documentation/mm/index.rst
+++ b/Documentation/mm/index.rst
@@ -25,14 +25,14 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
    oom
    allocation-profiling
 
-Legacy Documentation
-====================
+Unsorted Documentation
+======================
 
-This is a collection of older documents about the Linux memory management
-(MM) subsystem internals with different level of details ranging from
-notes and mailing list responses for elaborating descriptions of data
-structures and algorithms.  It should all be integrated nicely into the
-above structured documentation, or deleted if it has served its purpose.
+This is a collection of unsorted documents about the Linux memory management
+(MM) subsystem internals with different level of details ranging from notes and
+mailing list responses for elaborating descriptions of data structures and
+algorithms.  It should all be integrated nicely into the above structured
+documentation, or deleted if it has served its purpose.
 
 .. toctree::
    :maxdepth: 1
-- 
2.39.2

[PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

[SeongJae Park]

The memory allocation profiling document was added to the bottom of the
new outline.  Apparently it was not decided by well-defined guidelines
or a thorough discussions.  Rather than that, it was added there just
because there was no place for such unsorted documents.  Now there is
the chapter.  Move the document to the new place.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
index 15614df2b989..0be1c7503a01 100644
--- a/Documentation/mm/index.rst
+++ b/Documentation/mm/index.rst
@@ -23,7 +23,6 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
    page_cache
    shmfs
    oom
-   allocation-profiling
 
 Unsorted Documentation
 ======================
@@ -38,6 +37,7 @@ documentation, or deleted if it has served its purpose.
    :maxdepth: 1
 
    active_mm
+   allocation-profiling
    arch_pgtable_helpers
    balance
    damon/index
-- 
2.39.2

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

[Jonathan Corbet]

SeongJae Park <sj@kernel.org> writes:

> The memory allocation profiling document was added to the bottom of the
> new outline.  Apparently it was not decided by well-defined guidelines
> or a thorough discussions.  Rather than that, it was added there just
> because there was no place for such unsorted documents.  Now there is
> the chapter.  Move the document to the new place.

I'll take this for now, but it's truly sad to see new documentation
being added to the slushpile at the end.  It seems better to create a
"development tools" section in the new outline and put the allocation
profiling document there?

Thanks,

jon

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

[SeongJae Park]

On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <corbet@lwn.net> wrote:

> SeongJae Park <sj@kernel.org> writes:
> 
> > The memory allocation profiling document was added to the bottom of the
> > new outline.  Apparently it was not decided by well-defined guidelines
> > or a thorough discussions.  Rather than that, it was added there just
> > because there was no place for such unsorted documents.  Now there is
> > the chapter.  Move the document to the new place.
> 
> I'll take this for now, but it's truly sad to see new documentation
> being added to the slushpile at the end.  It seems better to create a
> "development tools" section in the new outline and put the allocation
> profiling document there?

I have no strong opinions about that.  Cc-ing Suren and Kent, as they are the
author of the allocation profiling document and hence might have some opinion.


Thanks,
SJ

[...]

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

[Randy Dunlap]

On 7/3/24 7:10 PM, Suren Baghdasaryan wrote:
> On Wed, Jul 3, 2024 at 4:00 PM SeongJae Park <sj@kernel.org> wrote:
>>
>> On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <corbet@lwn.net> wrote:
>>
>>> SeongJae Park <sj@kernel.org> writes:
>>>
>>>> The memory allocation profiling document was added to the bottom of the
>>>> new outline.  Apparently it was not decided by well-defined guidelines
>>>> or a thorough discussions.  Rather than that, it was added there just
>>>> because there was no place for such unsorted documents.  Now there is
>>>> the chapter.  Move the document to the new place.
>>>
>>> I'll take this for now, but it's truly sad to see new documentation
>>> being added to the slushpile at the end.  It seems better to create a
>>> "development tools" section in the new outline and put the allocation
>>> profiling document there?
>>
>> I have no strong opinions about that.  Cc-ing Suren and Kent, as they are the
>> author of the allocation profiling document and hence might have some opinion.
> 
> IMHO if this would be the only document belonging to "development
> tools" then keeping it under unsorted is fine.
> If more documents will fall into that category then Jonathan's
> suggestion makes sense to me. Looking at the current list, page_owner
> and maybe damon might be considered for this category as well.
> SeongJae, WDYT?
> Thanks,
> Suren.
> 

Documentation/dev-tools/ already contains 20 files.
Unless you want to keep it under Documentation/mm/, that is.

-- 
~Randy

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

[Suren Baghdasaryan]

On Wed, Jul 3, 2024 at 7:18 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> On 7/3/24 7:10 PM, Suren Baghdasaryan wrote:
> > On Wed, Jul 3, 2024 at 4:00 PM SeongJae Park <sj@kernel.org> wrote:
> >>
> >> On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <corbet@lwn.net> wrote:
> >>
> >>> SeongJae Park <sj@kernel.org> writes:
> >>>
> >>>> The memory allocation profiling document was added to the bottom of the
> >>>> new outline.  Apparently it was not decided by well-defined guidelines
> >>>> or a thorough discussions.  Rather than that, it was added there just
> >>>> because there was no place for such unsorted documents.  Now there is
> >>>> the chapter.  Move the document to the new place.
> >>>
> >>> I'll take this for now, but it's truly sad to see new documentation
> >>> being added to the slushpile at the end.  It seems better to create a
> >>> "development tools" section in the new outline and put the allocation
> >>> profiling document there?
> >>
> >> I have no strong opinions about that.  Cc-ing Suren and Kent, as they are the
> >> author of the allocation profiling document and hence might have some opinion.
> >
> > IMHO if this would be the only document belonging to "development
> > tools" then keeping it under unsorted is fine.
> > If more documents will fall into that category then Jonathan's
> > suggestion makes sense to me. Looking at the current list, page_owner
> > and maybe damon might be considered for this category as well.
> > SeongJae, WDYT?
> > Thanks,
> > Suren.
> >
>
> Documentation/dev-tools/ already contains 20 files.
> Unless you want to keep it under Documentation/mm/, that is.

I think it belongs more to mm than dev-tools TBH.

>
> --
> ~Randy

Re: [PATCH 4/4] Docs/mm/index: move allocation profiling document to unsorted documents chapter

[SeongJae Park]

On Wed, 3 Jul 2024 19:10:03 -0700 Suren Baghdasaryan <surenb@google.com> wrote:

> On Wed, Jul 3, 2024 at 4:00 PM SeongJae Park <sj@kernel.org> wrote:
> >
> > On Wed, 03 Jul 2024 16:18:42 -0600 Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > > SeongJae Park <sj@kernel.org> writes:
> > >
> > > > The memory allocation profiling document was added to the bottom of the
> > > > new outline.  Apparently it was not decided by well-defined guidelines
> > > > or a thorough discussions.  Rather than that, it was added there just
> > > > because there was no place for such unsorted documents.  Now there is
> > > > the chapter.  Move the document to the new place.
> > >
> > > I'll take this for now, but it's truly sad to see new documentation
> > > being added to the slushpile at the end.  It seems better to create a
> > > "development tools" section in the new outline and put the allocation
> > > profiling document there?
> >
> > I have no strong opinions about that.  Cc-ing Suren and Kent, as they are the
> > author of the allocation profiling document and hence might have some opinion.
> 
> IMHO if this would be the only document belonging to "development
> tools" then keeping it under unsorted is fine.
> If more documents will fall into that category then Jonathan's
> suggestion makes sense to me. Looking at the current list, page_owner
> and maybe damon might be considered for this category as well.
> SeongJae, WDYT?

I agree it makes more sense to have multiple documents under dedicated
sections.  And putting page_owner sounds not that odd to me.

DAMON is, however, not a tool but a framework that helps easy development of
access-aware kernel components.  Such components could be development tools and
system operations optimizations (using DAMOS).  So, IMHO, 'development tools'
section is not the perfect place for DAMON documents.

Actually, even for allocation-profiling and page_owner, I think 'development
tools' might not be a perfect category.  I understand those as features that
could be useful for system investigations of multiple purposes.

So, in short, I think it is not easy to find a perfect cateogry...


Thanks,
SJ

[...]

Re: [PATCH 0/4] Docs/mm: rename legacy docs to unsorted docs

[Jonathan Corbet]

SeongJae Park <sj@kernel.org> writes:

> The work for changing the memory mangement documentation outline has
> started from 2022.  For that, old documents have placed under new
> chapter, "Legacy Documentations".  The plan is to eventually move all
> old documentations into new outline, while asking new documents to be
> added on the new outline from the beginning.
>
> However, it is unclear where on the new outline each document should be
> placed for some cases.  Meanwhile, the name ("legacy") makes readers
> feel the documents under the chapter might be outdated or not actively
> maintained.  The absence of clear criteria for new outline also makes
> new documents difficult to find where those should be placed.  A new
> document was put on the bottom of the new outline recently, apparently
> not based on a clear guideline but just because it is the bottom of the
> list.
>
> Rename the "Legagy Documentation" chapter to "Unsorted Documentations"
> with minor fixups.

Series applied, thanks.

jon