All of lore.kernel.org
 help / color / mirror / Atom feed
From: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
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>
Subject: Re: [PATCH 13/17] docs: add Rust documentation
Date: Tue, 6 Jul 2021 02:06:52 +0200	[thread overview]
Message-ID: <CANiq72kvv1rYa-TY3EvM5tBc4d0bhuNH8u56b8PM4PQd1ngmTQ@mail.gmail.com> (raw)
In-Reply-To: <20210705050234.GB30964@1wt.eu>

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

  reply	other threads:[~2021-07-06  0:07 UTC|newest]

Thread overview: 73+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-04 20:27 [PATCH 00/17] Rust support ojeda
2021-07-04 20:27 ` [PATCH 01/17] kallsyms: support big kernel symbols (2-byte lengths) ojeda
2021-07-04 20:52   ` Linus Torvalds
2021-07-04 21:15     ` Miguel Ojeda
2021-07-04 21:28       ` Linus Torvalds
2021-07-04 21:04   ` Matthew Wilcox
2021-07-04 21:17     ` Miguel Ojeda
2021-07-04 21:33       ` Matthew Wilcox
2021-07-04 21:49         ` Matthew Wilcox
2021-07-04 22:07           ` Miguel Ojeda
2021-07-04 22:20         ` Gary Guo
2021-07-04 22:42           ` Matthew Wilcox
2021-07-04 23:14             ` Gary Guo
2021-07-13 18:02             ` Kent Overstreet
2021-07-04 21:20     ` Gary Guo
2021-07-05  4:35       ` Willy Tarreau
2021-07-04 20:27 ` [PATCH 02/17] kallsyms: increase maximum kernel symbol length to 512 ojeda
2021-07-14 18:20   ` Nick Desaulniers
2021-07-14 19:04     ` Linus Torvalds
2021-07-14 20:09       ` Eric W. Biederman
2021-07-14 20:21         ` Linus Torvalds
2021-07-14 20:48           ` Eric W. Biederman
2021-07-14 22:40             ` Linus Torvalds
2021-07-14 20:19     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 03/17] Makefile: generate `CLANG_FLAGS` even in GCC builds ojeda
2021-07-14 18:13   ` Nick Desaulniers
2021-07-14 18:16     ` Nick Desaulniers
2021-07-14 20:31     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 04/17] vsprintf: add new `%pA` format specifier ojeda
2021-07-07 20:31   ` Nick Desaulniers
2021-07-07 22:33     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 05/17] rust: add C helpers ojeda
2021-07-07 10:19   ` Marco Elver
2021-07-09 10:31     ` Marco Elver
2021-07-09 14:32     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 06/17] rust: add `compiler_builtins` crate ojeda
2021-07-04 20:27 ` [PATCH 07/17] rust: add `alloc` crate ojeda
2021-07-04 20:27 ` [PATCH 08/17] rust: add `build_error` crate ojeda
2021-07-04 20:27 ` [PATCH 09/17] rust: add `macros` crate ojeda
2021-07-04 20:27 ` [PATCH 10/17] rust: add `kernel` crate ojeda
2021-07-04 20:27 ` [PATCH 11/17] rust: export generated symbols ojeda
2021-07-04 20:27 ` [PATCH 12/17] Kbuild: add Rust support ojeda
2021-07-04 20:27 ` [PATCH 13/17] docs: add Rust documentation ojeda
2021-07-05  5:02   ` Willy Tarreau
2021-07-06  0:06     ` Miguel Ojeda [this message]
2021-07-06  2:09       ` Willy Tarreau
2021-07-14 18:37   ` Nick Desaulniers
2021-07-14 19:55     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 14/17] samples: add Rust examples ojeda
2021-07-04 20:27 ` [PATCH 15/17] scripts: add `generate_rust_analyzer.py` ojeda
2021-07-05  5:05   ` Willy Tarreau
2021-07-05 23:41     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 16/17] MAINTAINERS: Rust ojeda
2021-07-06  0:26   ` Pedro Tammela
2021-07-06 22:14     ` Miguel Ojeda
2021-07-04 20:27 ` [RFC PATCH 17/17] Android: Binder IPC in Rust (WIP) ojeda
2021-07-04 23:11 ` [PATCH 00/17] Rust support Miguel Ojeda
2021-07-07  6:43 ` Christoph Hellwig
2021-07-07 12:33   ` Miguel Ojeda
2021-07-07 12:50     ` Greg Kroah-Hartman
2021-07-07 14:07       ` Wedson Almeida Filho
2021-07-07 14:12         ` Christoph Hellwig
2021-07-07 15:02         ` Greg Kroah-Hartman
2021-07-07 20:56           ` Finn Behrens
2021-07-08  0:58             ` Matthew Wilcox
2021-07-08  6:39               ` [PATCH 00/17] Rust support, NVMe Geert Stappers
2021-07-08  8:29                 ` Finn Behrens
2021-07-22 22:55               ` [PATCH 00/17] Rust support Wedson Almeida Filho
2021-07-23  1:17                 ` Matthew Wilcox
2021-07-23 11:33                   ` [PATCH 00/17] Rust support, GPIO driver Geert Stappers
2021-07-23 15:08                 ` [PATCH 00/17] Rust support Keith Busch
2021-07-07 10:51 ` Marco Elver
2021-07-07 11:28   ` Miguel Ojeda

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CANiq72kvv1rYa-TY3EvM5tBc4d0bhuNH8u56b8PM4PQd1ngmTQ@mail.gmail.com \
    --to=miguel.ojeda.sandonis@gmail.com \
    --cc=alex.gaynor@gmail.com \
    --cc=ark.email@gmail.com \
    --cc=bobo1239@web.de \
    --cc=boqun.feng@gmail.com \
    --cc=d0u9.su@outlook.com \
    --cc=foxhlchen@gmail.com \
    --cc=gary@garyguo.net \
    --cc=geofft@ldpreload.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=jtitor@2k36.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kbuild@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=me@kloenk.de \
    --cc=mpe@ellerman.id.au \
    --cc=ojeda@kernel.org \
    --cc=rust-for-linux@vger.kernel.org \
    --cc=sylphrenadin@gmail.com \
    --cc=thesven73@gmail.com \
    --cc=torvalds@linux-foundation.org \
    --cc=w@1wt.eu \
    --cc=wedsonaf@google.com \
    --cc=zaidi.ayaan@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.