On Tue, Jul 06, 2021 at 02:06:52AM +0200, Miguel Ojeda wrote:

quoted

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.

quoted

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.

quoted

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