linux-kernel - Re: [PATCH 13/17] docs: add Rust documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CANiq72kvv1rYa-TY3EvM5tBc4d0bhuNH8u56b8PM4PQd1ngmTQ@mail.gmail.com>
Date:   Tue, 6 Jul 2021 02:06:52 +0200
From:   Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To:     Willy Tarreau <w@....eu>
Cc:     Miguel Ojeda <ojeda@...nel.org>,
        Linus Torvalds <torvalds@...ux-foundation.org>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        rust-for-linux <rust-for-linux@...r.kernel.org>,
        Linux Kbuild mailing list <linux-kbuild@...r.kernel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel <linux-kernel@...r.kernel.org>,
        Alex Gaynor <alex.gaynor@...il.com>,
        Geoffrey Thomas <geofft@...reload.com>,
        Finn Behrens <me@...enk.de>,
        Adam Bratschi-Kaye <ark.email@...il.com>,
        Wedson Almeida Filho <wedsonaf@...gle.com>,
        Boqun Feng <boqun.feng@...il.com>,
        Sumera Priyadarsini <sylphrenadin@...il.com>,
        Michael Ellerman <mpe@...erman.id.au>,
        Sven Van Asbroeck <thesven73@...il.com>,
        Gary Guo <gary@...yguo.net>,
        Boris-Chengbiao Zhou <bobo1239@....de>,
        Fox Chen <foxhlchen@...il.com>,
        Ayaan Zaidi <zaidi.ayaan@...il.com>,
        Douglas Su <d0u9.su@...look.com>, Yuki Okushi <jtitor@...6.org>
Subject: Re: [PATCH 13/17] docs: add Rust documentation

On Mon, Jul 5, 2021 at 7:02 AM Willy Tarreau <w@....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