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 B2EA3C7EE29 for ; Tue, 23 May 2023 08:50:44 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id DF7596B0074; Tue, 23 May 2023 04:50:43 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id DA78D900003; Tue, 23 May 2023 04:50:43 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id C7031900002; Tue, 23 May 2023 04:50:43 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id B51B36B0074 for ; Tue, 23 May 2023 04:50:43 -0400 (EDT) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id 741F31C72F8 for ; Tue, 23 May 2023 08:50:43 +0000 (UTC) X-FDA: 80820899166.11.0310072 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by imf06.hostedemail.com (Postfix) with ESMTP id B4250180017 for ; Tue, 23 May 2023 08:50:41 +0000 (UTC) Authentication-Results: imf06.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=Z84m+uEJ; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf06.hostedemail.com: domain of rppt@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=rppt@kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1684831841; 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=kvID/biUO5I6cNa4k+QoP/UtHgsRoKiGWy2F1A3VRjA=; b=hu8mpvZUQfqAyXRerwEpEgVoBsjL8c5eOFy/TcGvoO2LWMZti/Ixq2OvK4deKBh9i0/iaQ /4gH7BLpcEoB0om9V/fOxQSrgYNuEBdZ3JGJ1xsteSEzWLFMG92i5Y16lZOpZw4Ll0asPG DCvg7boxctF3jllKGp1vkl3hm0lZ6qI= ARC-Authentication-Results: i=1; imf06.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=Z84m+uEJ; dmarc=pass (policy=none) header.from=kernel.org; spf=pass (imf06.hostedemail.com: domain of rppt@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=rppt@kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1684831841; a=rsa-sha256; cv=none; b=nj6h66lwTYWAHxdo9J8i8WFcM7VMt/t8HxzBQLD5yWLISX8YcdRAb8NE5h5mQnO5Kvl8Fy vD8Cqsj12IVnKj5t0T2D9qJ6ZYiNCF9UE4FhpMn9omY3AmpbGS0qzIN5CtEdO5Js0Kb13u ruOy3J82ZrwcTB1kBrDjI+nsbigKPX4= Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 8649F6233F; Tue, 23 May 2023 08:50:40 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6C59BC433D2; Tue, 23 May 2023 08:50:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1684831839; bh=tMYXpizW8jr+9USxviIRGSoLiiqg4td4M+bCfyrCqgo=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=Z84m+uEJ8kbqZ3AtkfT4e3Okdpb0AZOBubPiyryqWuCX24eZcdKCySOnXurnZ62e8 BbDiqWAlQbILRoIh1K71nymbZChM7Gv/uOwxKu9GwQJxKG8ZzBUocZUjnOWoDWR57s wpzU/OdnV6iijUldqiG/q/fxk1OSjl8JRJO6js8psd2Mu1XzyPHOH0//8BNvuEV2a9 Vi68FrL5vynOEA+rXBj6np7tcJ9l4oJEdJycv2FurlzabN2P3JO4dS5/c+sUaCINT1 wMSAHvEogzkuQCgI7XYHbQCt8ZcZQvL0MyE2sLXsPZKHwxUgv6ijfCdlD5rejMe4/a Ne9kbjabATEhw== Date: Tue, 23 May 2023 11:50:34 +0300 From: Mike Rapoport To: David Rientjes Cc: Jonathan Corbet , Lorenzo Stoakes , linux-mm@kvack.org, Matthew Wilcox Subject: Re: [LSF/MM/BPF TOPIC] mm documentation Message-ID: 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-Rspam-User: X-Rspamd-Server: rspam12 X-Rspamd-Queue-Id: B4250180017 X-Stat-Signature: suci14dfjasubgfnbojbq5bpzx4x4re4 X-HE-Tag: 1684831841-747262 X-HE-Meta: U2FsdGVkX1+7RMu6QuXrdBjfWz070SabOo+RzUBjq50aKiLVJL4+UA3tJO9JiIi9HSPTMadoqZSAhwmeCqA2NLIrsVdHIq6cUSyuvsN+0l84IOmXqaNBXgQINwSwMbWU5I0jYxN09wF0eQX1LPXYVYu0ZXc57giXan5uqL1l0M/W77zR6CjueDslR8Xbasv/wDKRqVgbcLh1qZGWpKLqxQyQLJYW2HA9rLx+kR7O+1d2R9zGJqcgFl6askUw8drA8V2CyMD46Y/7VJ9Q6Uq1EuiG1DA05+Rlt9l3ff4SXcZuZgmnOPp368EPiPowTsS1/wrDsXHN/nB9+4C1hrjYsXJQ5AzbrAs7veMP1N0kuSgpSppw3rhNn2wk/HNhfbdXhE0R2AIimuWCEmDgnWTmp3+0yzpizBqsKbabfm65l623B3GnkPgJ/olRgG7nrb81Qo155h4xw01bgPT8zVeEOupIbMpiCglcRMSXaa/OhNsM7TcMX1Ns0xfmHsO8Bk+0Mf5QCEhaY8CfVu8tdHZ8R6jJ46QIHvLaYFUqpFe20bOovjJkoddoDYSrPn0thOqAaVJANWvWJBS7KaUiOPbCBAh/IrHqAUw89EXMYwK3ULjvsyv9Rwcyug4KvigkGJwb8CNx+koHXS0qWS8+fC2H9bAY09o/P96dCLiAeBO9X4W/rEWKainQFqPzk89pNeI91wcW/uFTznW17V/9OlHObWIK7i3XshPP3vLwPfsO9+VVh6RZJ8C562Agv68itqYxmPphH7804jjtTKr9IABGnBZRk4wIPuqqr22NZMMyFYdLf44C97D/jUSW6SoNETARH+JZSkjzacRMEEmf4/5qwqbuii7AW76RxsOWf4+J1vUrXPB58a7WpqG97904f47vsTguvSHGh/ZmdD2ak0+VCUkLZ/CVB4rmNplhNfJKbiwXA/m/figXMKsLZJ+wYqzt7KLc1+bvAOgMw2LBiP0 fXHjqrlY 6lYaXyezvWVepgTRmFSyx39S7E1H/0iRRO97QKD5KvoRr1gfvn7EPEgMt5+Nmn2UCm3/JxABqIgCcsiX/VQeG9KC29aH59+nha5lrDA4oX2SGLJtNPAIvGXcyEhUM2BlFtR/QN8GkQ4gBhSckNNgo9oxESeGBteRUdvwLiCu8zA+hCmGk/Tyha4DIBXxMzn5r4+WkqyzB78+B2tjR/E/CrQbbKM6aSJah1bhQu/pTQPu5dYN2vCBLTLrlfLFRK6E3mn96kSHUNckK+ICcF233DgHIiJWbp2sSqanw X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, 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. Well, yes and no. Willy did a decent job of updating the docs along with the folio conversion and out of hundreds of commits only about 50 touch Documentation/. I believe there are still some gaps, but I'd imaging they are not that big. With per-vma lock I believe there are some updates pending and if we had more elaborate documentation it would have required more work, but still I don't think it would have been something large scale, but rather semi-mechanical replacement of mmap_lock mentions with vma lock and updating a few paragraphs that actually described the locking. But this is all theory of course :) > 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? What we have now is Mel's book and some assorted pieces here and there, so having more documentation seems really useful to me, even if it won't always be up to date. I agree with Lorenzo that the most important bits, like, for example, general description of allocation, reclaim, compaction, won't require frequent changes and I think it'll be manageable. > 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? The hackers and maintainers, yes. I believe that as a part of our process we should pay more attention to documentation and ask contributors to update the documentation along with the code. I personally do it for some time now, but unfortunately I can't always keep up with the pace. -- Sincerely yours, Mike.