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 X-Spam-Level: X-Spam-Status: No, score=-3.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4C9F8C433ED for ; Thu, 20 May 2021 14:19:41 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id CD78E61184 for ; Thu, 20 May 2021 14:19:40 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org CD78E61184 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 391F48E0015; Thu, 20 May 2021 10:19:40 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 341D18E0012; Thu, 20 May 2021 10:19:40 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 231898E0015; Thu, 20 May 2021 10:19:40 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0145.hostedemail.com [216.40.44.145]) by kanga.kvack.org (Postfix) with ESMTP id E49A28E0012 for ; Thu, 20 May 2021 10:19:39 -0400 (EDT) Received: from smtpin16.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with ESMTP id 5C914181AC9B6 for ; Thu, 20 May 2021 14:19:39 +0000 (UTC) X-FDA: 78161817678.16.76505B0 Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) by imf22.hostedemail.com (Postfix) with ESMTP id ECC78C0042FA for ; Thu, 20 May 2021 14:19:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=In-Reply-To:Content-Type:MIME-Version: References:Message-ID:Subject:Cc:To:From:Date:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=oC+YhFNmJbcV9OnbQ7S+PxXNJwDoQxAUyDbiKmv2pIM=; b=Ef5sESQQR+NtPb3uIxi3Z2ocWA sWRgujDSw8NIHGu/Pic5uM+fWLOkJ1KhxC9zmzwBbo589B4S+ZzB618KRKMGXi2gS1s4uscCdR88d pEKTFvl48ET7UKru2sMjIa6wwQyQUNd/foqDO8b3bC53RkRYBnMBAnNk7gcQUWSAWL+99uerWEqzg TTDrcgSakfK0L4ld5n3rflMxoYoryvlc6y/guURqRQdc+5zASQAPDM6DO3+xQbSek35Y+sX+q46vL Cm4uBASLPL5UkeoHnWS0X00fRlArMdoYsZjHg6OjQ4zoKHSmyeWJ6mzORpjh13cJm/BFRCxmWVorQ /LZxIdvg==; Received: from willy by casper.infradead.org with local (Exim 4.94 #2 (Red Hat Linux)) id 1ljjW0-00G7jU-3I; Thu, 20 May 2021 14:19:14 +0000 Date: Thu, 20 May 2021 15:19:08 +0100 From: Matthew Wilcox To: Mike Rapoport Cc: lsf-pc@lists.linux-foundation.org, linux-mm@kvack.org Subject: Re: [LSF/MM TOPIC] mm documentation Message-ID: References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspamd-Queue-Id: ECC78C0042FA Authentication-Results: imf22.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=Ef5sESQQ; spf=none (imf22.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org; dmarc=none X-Rspamd-Server: rspam04 X-Stat-Signature: dtkyafkst6qu3wy63pjcd8ze8kq96c4d X-HE-Tag: 1621520376-660898 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 Thu, May 20, 2021 at 11:56:09AM +0300, Mike Rapoport wrote: > The mm documentation is, well, not entirely up to date. We can opt for > dropping the outdated parts, which would generate a nice negative > diffstat, but identifying the outdated documentation requires nearly > as much effort as updating it, so I think that making and keeping > the docs up to date would be a better option. > > I'd like to discuss what can be done process-wise to improve the > situation. > > Some points I had in mind: > > * Pay more attention to docs during review > * Set an expectation level for docs accompanying a changeset > * Spend some cycles to review and update the existing docs > * Spend some more cycles to add new documentation > * Participate in prorams like Google Season of Docs > > I'd appreciate a discussion about how we can improve the existing memory > management documentation so that a reader can get a coherent view of it, > what are the gaps (although they are too many), and what would be the best > way to close these gaps. I think we have four target audiences for mm documentation, - Sysadmins/user space programmers who are trying to make their system perform well. They need documentation of the proc/sys/cmdline/... parameters that the MM pays attention to. - Kernel programmers who are not (and do not wish to be) MM developers. Filesystem developers, device driver developers, networking developers. They need kernel-doc for our exported functions and advice for when to use and not use particular functions/flags. - Programmers who want to "get started" in the MM area. They may or may not be familiar with Linux internals (perhaps they're moving from another kernel, perhaps their experience is with some other part of Linux; perhaps they have no experience at all). I think these people are probably well served by Mel's book, even if it is a few years old now. - Each other. The MM is huge these days, and I certainly don't understand how it all interacts with itself. I think we actually do a pretty good job of talking to each other and writing commit messages. I think it's really the second group where we do the worst job of documentation, but I may be biased. It's certainly where I'm focusing my documentation efforts.