On Mon, Jul 5, 2021 at 7:02 AM Willy Tarreau [off-list ref] 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