From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 90E62C77B73 for ; Mon, 22 May 2023 07:47:33 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 04B01900002; Mon, 22 May 2023 03:47:33 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id F3E6C6B0075; Mon, 22 May 2023 03:47:32 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id E062C900002; Mon, 22 May 2023 03:47:32 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0014.hostedemail.com [216.40.44.14]) by kanga.kvack.org (Postfix) with ESMTP id D1EDA6B0074 for ; Mon, 22 May 2023 03:47:32 -0400 (EDT) Received: from smtpin13.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id 931A81A0496 for ; Mon, 22 May 2023 07:47:32 +0000 (UTC) X-FDA: 80817111144.13.136F485 Received: from mail-wr1-f47.google.com (mail-wr1-f47.google.com [209.85.221.47]) by imf05.hostedemail.com (Postfix) with ESMTP id 9E833100002 for ; Mon, 22 May 2023 07:47:30 +0000 (UTC) Authentication-Results: imf05.hostedemail.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=dFFtssZR; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf05.hostedemail.com: domain of lstoakes@gmail.com designates 209.85.221.47 as permitted sender) smtp.mailfrom=lstoakes@gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1684741650; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=OReMkr5WFWBKADy1IsQbGKXMsh2pMlIlykYz7yrKFCQ=; b=5LqugDherOtN2H8NLZIBzYDsbp0rF6ekiop7m1hYn5LOvf/NJ4fCu1t9wd0/74pRS75wkU ked0tbOuPwiNLVF+nqHDLwzE/Y6Z0XMyK7vCQCVzX4ItA15WDkwJpxaSLYlQx9+np+dQ3E w9yfbYEa+r+Azl8U0gTdp2rrakaD3RM= ARC-Authentication-Results: i=1; imf05.hostedemail.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=dFFtssZR; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (imf05.hostedemail.com: domain of lstoakes@gmail.com designates 209.85.221.47 as permitted sender) smtp.mailfrom=lstoakes@gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1684741650; a=rsa-sha256; cv=none; b=W6WrzoyueT9XP4BwdLPn5gQxW8Ex5kAtwgrPFVJ7kaOxaw8a0k481vKAsTknA+eDFdALpY 7amFyOVW0ngbIPioNBB89GfezZinI0MO+TEbmK9t3UKwqIlwLYB01kfb7D0ckaQ7eNPuPw 1W4WExi2m1JtI/zSu3qnyONQTHD/o+Q= Received: by mail-wr1-f47.google.com with SMTP id ffacd0b85a97d-306dbad5182so3640418f8f.1 for ; Mon, 22 May 2023 00:47:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1684741649; x=1687333649; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:from:to:cc:subject:date:message-id:reply-to; bh=OReMkr5WFWBKADy1IsQbGKXMsh2pMlIlykYz7yrKFCQ=; b=dFFtssZRRgF2MIqYqACPt2+Xdvf+nMGyLKiZ7XxDocXIjBK7YpEdp1nCC1QodnPJzL D/QkggkLeInQZrPRV7jvT8SweZWc9YqiZG9sKn4IJh3WU7NJzKfeWj5ClWTzIC21z5wb aI/be0TKIM8dDFt3RXyDvU6PbAQAzx7VYNLo58ZljdA8yEqARcu7FxFI2nud8WlhXzoM zylwH9AV5Aa6WAgCqId+O50bEhT495e4eZj+O8Lco3d/UcJ7cHK0eEr/BrDgHdlEotlR K5QxALVnSTnTIKPBLeud31/2WA8XfFD/34HtFNIdSD4N3b/dwj2uVJgM414XttsT9lcq ATzw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1684741649; x=1687333649; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=OReMkr5WFWBKADy1IsQbGKXMsh2pMlIlykYz7yrKFCQ=; b=CPpTStrIhNocA+83+h3Dx6EioxYXeBMDnc2Sp5RqLh3Liij34A5Iqoahnk5KTtaA59 c/0dARIaaX18nlXPJTFf2BrCPnvPQiqEbkypYCB0MybdS/QRLyjyVy7i+nPuF8aKAmFa TgwOZggk9t7dlSF46HWBVFpxtNoitMnoWcZOfooCPQB9cDHnKr6oRCC990pyH2CFwtT6 dcAsD8K+uc2/brJHp++anwuGQyxydxabWunyZSJsCvT5sNstLqdZ+x2ppGpHLoMxn1/h mGQn7M1oiK3LgQ05lUF6X2Zz//Zg+sMKBbiTVsYDPcvTzeObyqmrkkHvgy0J3F6F+sGI EgLw== X-Gm-Message-State: AC+VfDxpRsWdGgPIVA9RwRLPMvmhWAUgMLn69suxGxkzAkVQNqh7pTjI KQl8I/gCIvN2Ce9ROBls6Mk= X-Google-Smtp-Source: ACHHUZ7LXlClUnFDh4uZmc63gqWLVKA1ztdhY5UDCLaNUsxPMjOKeCL8UqjMzszdT7q/7sm65Zwn1w== X-Received: by 2002:adf:f2d2:0:b0:307:977a:e693 with SMTP id d18-20020adff2d2000000b00307977ae693mr6776650wrp.59.1684741648834; Mon, 22 May 2023 00:47:28 -0700 (PDT) Received: from localhost (host81-154-179-160.range81-154.btcentralplus.com. [81.154.179.160]) by smtp.gmail.com with ESMTPSA id k2-20020adfd842000000b0030647449730sm6785681wrl.74.2023.05.22.00.47.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 22 May 2023 00:47:27 -0700 (PDT) Date: Mon, 22 May 2023 08:47:26 +0100 From: Lorenzo Stoakes To: David Rientjes Cc: Jonathan Corbet , Mike Rapoport , linux-mm@kvack.org, Matthew Wilcox Subject: Re: [LSF/MM/BPF TOPIC] mm documentation Message-ID: <88c7533d-ea15-4b81-9160-e112724721f1@lucifer.local> References: <20230512173732.GI4135@kernel.org> <5aa1cb82-b39e-47c9-bb7a-c6145b2acbd3@lucifer.local> <87lehocnxv.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspamd-Server: rspam09 X-Rspamd-Queue-Id: 9E833100002 X-Stat-Signature: phdd535p5js8zuqi7parxue8nuanfodx X-Rspam-User: X-HE-Tag: 1684741650-847387 X-HE-Meta: U2FsdGVkX1/F2/S3W8rF++xb2oojaTeR4yE6hnRKVdsNCq1iUU4FEb8wkfVHzkuXkae0rxGkkgzMaQ3iv/8STSJM2eYA8dRGM4ls5u9CWYqH5MlQzTL5rO91sYDqaHyioG3KpRHDTzd1CcxLUwVo3cCLzjY3Z1el2SERePturKcoCffm2QQTfvl1yPNfkTjzL9V03iBDcRFwZtwrzCAxLOeHI6j3/TCjjCP3OYXZnoC1y90SH7Mq7dHzPYEbKTsGePmcp00AIghbkd5bmek5ZgghzeAkOiKIbuv48MNx/qMuA571KCgM0Eo4J7fSV135OpISqCajKvsz9py0seUYZhombltzUhDzHQ9snOXnBomCnSgsqN268Pj6T6xX2W6/Jci+n/JVQSIV9ZNGHp+ZEPSQ8c53J+FPKJLAqPcf4yRTqysO8frsv3EFDWGlBG4VzmVfNWfYt5uMGrQPm71D9EcH2Xip//7a5rsTNsylkxvHtc3ZBU/CyMSUvNnvP8BEgG4KJdA2lft5QKQiXglJKelJSK7J/sslcTPIhnuuz6DSTtILJ/PJmbPUr1lW6GrcZkBoQ0IhxPRe3GmmSP0oYdGrLT/QiR++Z+EdNxTvga7CDD9XNcRkHwif/wt7SzUGkk/yYKacge9hNpKEGNOxM+rznDdN0NaYWPZaqCZJOqRqpHdlQl37vlKcwG07b/BZ60MBpK68RI6Q/yaIWZwjrx/r3UEdDdrX77fFGLyOZJQdI9kgrWlP+MN2JKwIugzuLni4ucpe5P1sRLJ1UEa9fjbg86OBX1qHQoIJXexBmRFxHuaB6qbP/w2t9IkVSzM2bjbZo37FEN0By5zNhapS1I1LJYvDrGloEFFMb8sCM49JF55LQXILDcLRrQWMXnOcf31D5ozsmWSwwL0W1ATC40rl8g9lAKKZBwvvME6fmuBPlRnw151++K2+Mhfj2lLSX7yIKW3+6RNWd64MEXE AHwy5Mse 01qo5BjEvrurJQ9QqLxOS1a8qjFA80tveaqpyWTsy9NCel3U8RTLpemWZKPaKyWhXS6oRLq0JosIhnQjy4k3d1XkDNK9mdJqs/h98rVRzHYroS+aJmie8jr5pzsTCHVhv1D1dAsdiwcApkrU4k3PtJKN+wrTwMK2PR1CDjIURvfX7FLmmePSQjIs3chBs50cWBNA3oZcTALe1eOfU8CBXGGKsRWRZNy0d2Vaf4/rFMtSdEMV5fb46wsDUYRcJVnXUHF6HZvbo1cKET482NftTvpsEWmaKZDm3xCcKlEcJDAUEpd7kJ74iXxpjj9OOfr+HbVtCyxkH6WeO6wimUDo/DQYF1nUMChKA3rv7apP4GZhu+b8IPS8jMKMunQXUFbjgA2Vmo7Ttu7I7O3w= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000005, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: On Sun, May 21, 2023 at 04:50:57PM -0700, David Rientjes wrote: > On Tue, 16 May 2023, Jonathan Corbet wrote: > > > >> > And if we are going to participate in projects like Outreachy and Google > > >> > Season of Docs, we can suggest a project "Convert Lorenzo's book to kernel > > >> > documentation" alongside "Write more MM documentation" project. > > >> > > >> Yeah, this could be a good starting point actually, as rather than starting > > >> from zero, people would have some material that they can cross-check. > > > > > > I'm going to suggest "MM docs" for the next Outreachy round and I'll ping > > > you then about the "Convert Lorenzo's book to kernel documentation" > > > project. > > > > > > As for participation in the Google Season of Docs, maybe this should be > > > more broad than only mm docs. > > > Jon, what do you think? > > > > Sorry, I'm still catching up from travel and have a lot of digging out > > to do... > > > > Converting relevant bits of the book to RST seems like a great project. > > In theory pandoc can do that, but I've never tried it and can imagine > > that a fair amount of tweaking is required. > > > > Season of docs definitely seems worth looking into, but we've missed the > > bus for this year. Something to keep in mind next January. > > > > I think both of these programs are useful for importing mm documentation > that is up-to-date at the time that it's imported. > > I'm concerned that the documentation will quickly become out of date, > however. If mm documentation were imported before the introduction of > folios or per-vma locking, for example, it would likely need large scale > changes. > Yeah, this is one of the ways in which the book differs quite a bit from the documentation process - I get to 'cheat' in that I have frozen the target on v6, skip all arches but x86-64 and also don't cover quite a few things for the sake of brevity/feasibility. Key purpose is to a. describe core algorithms and concepts that should (probably) not change too much [relevant to mm docs] and b. describe code that might become/already is obsolete in considerable detail, intending to give a smaller delta to book/code + provide basis for reader to go to code [not relevant to mm docs]. Obviously kernel documentation cannot take this approach. > Maybe the idea is that any documentation, no matter how outdated, is > better than no documentation. This may not always be the case, however: > how often have people become frustrated that the documentation that does > exist doesn't actually reflect the current state of the kernel anymore? > My thinking on book/doc overlap was precisely the area for which docs can be written without too much concern about obsolescence - core concepts/algorithms that are highly unlikely to change any time soon. This kind of area seems like a good early target for docs, and Mike has already gone down this road with the (excellent) node/zone documentation. I do want to reiterate what I raised at LSF/MM, which is that documentation is the ultimate bikeshed bait and we do have to try to reach a bar of 'good enough' to prevent endless nitpicks slowing documentation patches to a glacial pace. Perhaps providing broad strokes descriptions of e.g. page cache/reclaim can set the groundwork and momentum for future changes. Adjusting a document to tweak a description of how reclaim works in scenario XYZ is a lot less daunting than having to write something from scratch. > Mike, I think one of the goals you were trying to achieve at LSF/MM/BPF > was how this documentation would not only get originally created/imported, > but also how it would stay relatively up-to-date. To keep the > documentation current, I think the burden would likely need to fall on the > kernel hakcers who are actually developing the code? > I will let Mike comment on this obviously but from my perspective and as discussed at LSF/MM, process seems to me to be absolutely key to this - new features such as per-VMA locks or maple trees should proactively _require_ documentation in my view. Equally changes to logic that would render documentation out of date should require changes there also. As a hobbyist my constraints differ quite a bit from you guys working full time on this so I realise there might be difficulty justifying time on such things, but maintainers have the ability to insist + establish new requirements :) Just my 2 English pence however, as the process side is something that maintainers need to figure out. I feel like this is a game of two halves - the core algos are the low-hanging fruit, as they can be written at our leisure. The detailed stuff that is in constant flux really requires a change in process to be viable.