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;
MIME-Version: 1.0
References: <20210704202756.29107-1-ojeda@kernel.org> <20210704202756.29107-14-ojeda@kernel.org>
 <20210705050234.GB30964@1wt.eu>
In-Reply-To: <20210705050234.GB30964@1wt.eu>
From:   Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Date:   Tue, 6 Jul 2021 02:06:52 +0200
Message-ID: <CANiq72kvv1rYa-TY3EvM5tBc4d0bhuNH8u56b8PM4PQd1ngmTQ@mail.gmail.com>
Subject: Re: [PATCH 13/17] docs: add Rust documentation
To:     Willy Tarreau <w@1wt.eu>
Cc:     Miguel Ojeda <ojeda@kernel.org>,
        Linus Torvalds <torvalds@linux-foundation.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        rust-for-linux <rust-for-linux@vger.kernel.org>,
        Linux Kbuild mailing list <linux-kbuild@vger.kernel.org>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        linux-kernel <linux-kernel@vger.kernel.org>,
        Alex Gaynor <alex.gaynor@gmail.com>,
        Geoffrey Thomas <geofft@ldpreload.com>,
        Finn Behrens <me@kloenk.de>,
        Adam Bratschi-Kaye <ark.email@gmail.com>,
        Wedson Almeida Filho <wedsonaf@google.com>,
        Boqun Feng <boqun.feng@gmail.com>,
        Sumera Priyadarsini <sylphrenadin@gmail.com>,
        Michael Ellerman <mpe@ellerman.id.au>,
        Sven Van Asbroeck <thesven73@gmail.com>,
        Gary Guo <gary@garyguo.net>,
        Boris-Chengbiao Zhou <bobo1239@web.de>,
        Fox Chen <foxhlchen@gmail.com>,
        Ayaan Zaidi <zaidi.ayaan@gmail.com>,
        Douglas Su <d0u9.su@outlook.com>, Yuki Okushi <jtitor@2k36.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Mon, Jul 5, 2021 at 7:02 AM Willy Tarreau <w@1wt.eu> wrote:
>
> Miguel, the wording and style in this file is not much welcome, it looks
> like a copy-paste of an e-mail in the doc. The exclamation above "this is
> a very good news" doesn't really belong to a doc, and for readers who don't
> understand why it appears as a good news to the writer, it probably is an
> even less good news.

Yes, I can definitely be more formal here.

> 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.

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.

> 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.

> 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!

Cheers,
Miguel