Received: by 2002:a05:6a10:f3d0:0:0:0:0 with SMTP id a16csp4273346pxv; Mon, 5 Jul 2021 19:11:29 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwpEA+kTnJmiThXMfd2/s4/MTgeYFKwDTWOfp4MtjEeYRg9vz/lH8es19qcYBBol1fZdmcK X-Received: by 2002:a05:6402:348b:: with SMTP id v11mr19815300edc.231.1625537489732; Mon, 05 Jul 2021 19:11:29 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1625537489; cv=none; d=google.com; s=arc-20160816; b=i2XA+ZQtn8dfUMthd7XdHAZ2GVe0iV4tKniaDC/P1LLLwCiYIaMj/7S4F7K9QiQ9jo NMKfv0ZKY0jWVQd44lsv5BS7F51WgQidtE3L5saenZaekMaCcb58pa6+Ow0kG1jkYUPY PRSFIpGwQFrONJ4h6F/NV8IFsUWAUoX87lpqzrHJfufi8982yuJckTBvhE3MSf5NWcIp 5R4+heuKyOtf1Ig/re49cKlox7pX5aVQBWo8aYva6Nmau0+sKe5IjfPaYp78/c5TBV5O ooAII/nCRXtAGyIleeiCPdT61A2SCfZqjtI5ynCCzaib59TtfAPoFzeUO3maYI2h+0Jf nwVQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:user-agent:in-reply-to:content-disposition :mime-version:references:message-id:subject:cc:to:from:date; bh=GcKnog+PT1q50ZJWI/VQgJ9uhmjiBqAaj48YKsLP/jE=; b=bs68Dlyakn551FAWFTdeY0q/GY+0qnuhaHDHV+ykkdzdTBW3yOb4SZ9kGrsxFV3H3R 3ffJqkNVftw+9ivdofIXnMsn9zlg7+BssjYr1hkAkn8uGCZyBxKfwb2qwAlSEI3+CJHB 6Kcy5kbFwpVyWyndRDbq0OHSV0J62+1rs/LaXGlu6Rk9inWy7Sv8BRsisGe9Zuz2b/TR KPgkZeKqiW/k8IjyjHhIzEJwcljluTWkr4BMrecwDqNkOxM8HTz0IsI6e60rdAdmJctO pGy5yHxK6t/VSmAEblN26ud6XTkie0juiM3bcFcGWyil14NFi/VS1Uilaz2Jz4MNUqsn 5oOA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id v7si13618514edj.328.2021.07.05.19.11.06; Mon, 05 Jul 2021 19:11:29 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229812AbhGFCMw (ORCPT + 99 others); Mon, 5 Jul 2021 22:12:52 -0400 Received: from wtarreau.pck.nerim.net ([62.212.114.60]:57267 "EHLO 1wt.eu" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229753AbhGFCMv (ORCPT ); Mon, 5 Jul 2021 22:12:51 -0400 Received: (from willy@localhost) by pcw.home.local (8.15.2/8.15.2/Submit) id 16629og3032325; Tue, 6 Jul 2021 04:09:50 +0200 Date: Tue, 6 Jul 2021 04:09:50 +0200 From: Willy Tarreau To: Miguel Ojeda Cc: Miguel Ojeda , Linus Torvalds , Greg Kroah-Hartman , rust-for-linux , Linux Kbuild mailing list , Linux Doc Mailing List , linux-kernel , Alex Gaynor , Geoffrey Thomas , Finn Behrens , Adam Bratschi-Kaye , Wedson Almeida Filho , Boqun Feng , Sumera Priyadarsini , Michael Ellerman , Sven Van Asbroeck , Gary Guo , Boris-Chengbiao Zhou , Fox Chen , Ayaan Zaidi , Douglas Su , Yuki Okushi Subject: Re: [PATCH 13/17] docs: add Rust documentation Message-ID: <20210706020950.GA32301@1wt.eu> References: <20210704202756.29107-1-ojeda@kernel.org> <20210704202756.29107-14-ojeda@kernel.org> <20210705050234.GB30964@1wt.eu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, Jul 06, 2021 at 02:06:52AM +0200, Miguel Ojeda wrote: > > In general you should avoid "we" and "you" when writing documentation. > > Prefer passive forms instead, which do not place a barrier between those > > who teach and those who learn. It's generally considered more inclusive > > in that it makes the reader not feel outside of the team who wrote it. > > When I was writing this, I wondered the same thing, because in Spanish > this does look quite bad (in the sense of being too informal), and we > use the passive forms a lot more for things like this. So I am fine > rewriting this. Also, mixing we/you is not ideal either. Indeed, I can imagine how informal it could sound in Spanish. > Having said that, I am not sure about English and whether people > prefer to read text with the passive form or not. In `Documentation/` > there seems to be a lot of "we"s and "you"s, but they could be wrong > too, of course. It's possible. While I've seen it used a lot in training or step-by-step instructions which aim to guide the reader through a procedure, it's not commonly found in documentation. One principle to keep in mind is to only focus on the subject. If your documentation describes a component or process and does not involve a human, there's no reason for introducing this human there. If it explicitly aims at the human (e.g. instructions), of course it makes sense. But anything that can end up in a script does not require a human and should avoid we/you. > > An additional note is that if the language imposes such unusual constraints > > on the editor, you should probably point to various known settins for most > > well-known editors. > > Are you referring about style? If yes, it is possible to write the > code with a text editor with no extra features and then format it, so > that should not be a problem. Yes that's my point, it will likely be the first experience for most casual visitors who have no idea how to reconfigure their editor or who don't want to risk to break their existing config. > > You should also clearly indicate how to recheck (or adjust) individual > > files, not just say that the command supports it. > > Sounds good -- I will do that. > > Thanks a lot for reviewing the docs! You're welcome. Willy