From: Mike Rapoport <rppt@linux.vnet.ibm.com>
To: Matthew Wilcox <willy@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
Andrew Morton <akpm@linux-foundation.org>,
Andrey Ryabinin <aryabinin@virtuozzo.com>,
Richard Henderson <rth@twiddle.net>,
Ivan Kokshaysky <ink@jurassic.park.msu.ru>,
Matt Turner <mattst88@gmail.com>, Tony Luck <tony.luck@intel.com>,
Fenghua Yu <fenghua.yu@intel.com>,
Ralf Baechle <ralf@linux-mips.org>,
James Hogan <jhogan@kernel.org>,
Michael Ellerman <mpe@ellerman.id.au>,
Alexander Viro <viro@zeniv.linux.org.uk>,
linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
kasan-dev@googlegroups.com, linux-alpha@vger.kernel.org,
linux-ia64@vger.kernel.org, linux-mips@linux-mips.org,
linuxppc-dev@lists.ozlabs.org, linux-fsdevel@vger.kernel.org,
linux-mm@kvack.org
Subject: Re: [PATCH 00/32] docs/vm: convert to ReST format
Date: Sun, 15 Apr 2018 20:29:11 +0300 [thread overview]
Message-ID: <20180415172910.GA31176@rapoport-lnx> (raw)
In-Reply-To: <20180413202108.GA30271@bombadil.infradead.org>
On Fri, Apr 13, 2018 at 01:21:08PM -0700, Matthew Wilcox wrote:
> On Fri, Apr 13, 2018 at 01:55:51PM -0600, Jonathan Corbet wrote:
> > > I believe that keeping the mm docs together will give better visibility of
> > > what (little) mm documentation we have and will make the updates easier.
> > > The documents that fit well into a certain topic could be linked there. For
> > > instance:
> >
> > ...but this sounds like just the opposite...?
> >
> > I've had this conversation with folks in a number of subsystems.
> > Everybody wants to keep their documentation together in one place - it's
> > easier for the developers after all. But for the readers I think it's
> > objectively worse. It perpetuates the mess that Documentation/ is, and
> > forces readers to go digging through all kinds of inappropriate material
> > in the hope of finding something that tells them what they need to know.
> >
> > So I would *really* like to split the documentation by audience, as has
> > been done for a number of other kernel subsystems (and eventually all, I
> > hope).
> >
> > I can go ahead and apply the RST conversion, that seems like a step in
> > the right direction regardless. But I sure hope we don't really have to
> > keep it as an unorganized jumble of stuff...
>
> I've started on Documentation/core-api/memory.rst which covers just
> memory allocation. So far it has the Overview and GFP flags sections
> written and an outline for 'The slab allocator', 'The page allocator',
> 'The vmalloc allocator' and 'The page_frag allocator'. And typing this
> up, I realise we need a 'The percpu allocator'. I'm thinking that this
> is *not* the right document for the DMA memory allocators (although it
> should link to that documentation).
>
> I suspect the existing Documentation/vm/ should probably stay as an
> unorganised jumble of stuff. Developers mostly talking to other MM
> developers. Stuff that people outside the MM fraternity should know
> about needs to be centrally documented. By all means convert it to
> ReST ... I don't much care, and it may make it easier to steal bits
> or link to it from the organised documentation.
The existing Documentation/vm contains different types of documents. Some
are indeed "Developers mostly talking to other MM developers". Some are
really user/administrator guides. Others are somewhat in between.
I took another look at what's there and I think we can actually move part
of Documentation/vm to Documentation/admin-guide. We can add
Documentation/admin-guide/vm/ and title it "Memory Management Tuning" or
something like that. And several files, e.g. hugetlbpage, ksm, soft-dirty
can be moved there.
--
Sincerely yours,
Mike.
next prev parent reply other threads:[~2018-04-15 17:29 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-03-21 19:22 [PATCH 00/32] docs/vm: convert to ReST format Mike Rapoport
2018-03-21 19:22 ` [PATCH 01/32] docs/vm: active_mm.txt " Mike Rapoport
2018-03-21 19:22 ` [PATCH 02/32] docs/vm: balance: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 03/32] docs/vm: cleancache.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 04/32] docs/vm: frontswap.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 05/32] docs/vm: highmem.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 06/32] docs/vm: hmm.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 07/32] docs/vm: hugetlbpage.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 08/32] docs/vm: hugetlbfs_reserv.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 09/32] docs/vm: hwpoison.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 10/32] docs/vm: idle_page_tracking.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 11/32] docs/vm: ksm.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 12/32] docs/vm: mmu_notifier.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 13/32] docs/vm: numa_memory_policy.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 14/32] docs/vm: overcommit-accounting: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 15/32] docs/vm: page_frags " Mike Rapoport
2018-03-21 19:22 ` [PATCH 16/32] docs/vm: numa: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 17/32] docs/vm: pagemap.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 18/32] docs/vm: page_migration: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 19/32] docs/vm: page_owner: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 20/32] docs/vm: remap_file_pages.txt: conert " Mike Rapoport
2018-03-21 19:22 ` [PATCH 21/32] docs/vm: slub.txt: convert " Mike Rapoport
2018-03-21 19:22 ` [PATCH 22/32] docs/vm: soft-dirty.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 23/32] docs/vm: split_page_table_lock: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 24/32] docs/vm: swap_numa.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 25/32] docs/vm: transhuge.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 26/32] docs/vm: unevictable-lru.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 27/32] docs/vm: userfaultfd.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 28/32] docs/vm: z3fold.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 29/32] docs/vm: zsmalloc.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 30/32] docs/vm: zswap.txt: " Mike Rapoport
2018-03-21 19:22 ` [PATCH 31/32] docs/vm: rename documentation files to .rst Mike Rapoport
2018-03-21 19:22 ` [PATCH 32/32] docs/vm: add index.rst and link MM documentation to top level index Mike Rapoport
2018-03-29 21:46 ` [PATCH 00/32] docs/vm: convert to ReST format Jonathan Corbet
2018-04-01 6:38 ` Mike Rapoport
2018-04-10 10:23 ` Mike Rapoport
2018-04-13 19:55 ` Jonathan Corbet
2018-04-13 20:21 ` Matthew Wilcox
2018-04-15 17:29 ` Mike Rapoport [this message]
2018-04-15 17:36 ` Mike Rapoport
2018-04-16 20:35 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180415172910.GA31176@rapoport-lnx \
--to=rppt@linux.vnet.ibm.com \
--cc=akpm@linux-foundation.org \
--cc=aryabinin@virtuozzo.com \
--cc=corbet@lwn.net \
--cc=fenghua.yu@intel.com \
--cc=ink@jurassic.park.msu.ru \
--cc=jhogan@kernel.org \
--cc=kasan-dev@googlegroups.com \
--cc=linux-alpha@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-ia64@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mips@linux-mips.org \
--cc=linux-mm@kvack.org \
--cc=linuxppc-dev@lists.ozlabs.org \
--cc=mattst88@gmail.com \
--cc=mpe@ellerman.id.au \
--cc=ralf@linux-mips.org \
--cc=rth@twiddle.net \
--cc=tony.luck@intel.com \
--cc=viro@zeniv.linux.org.uk \
--cc=willy@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).