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

[Willy Tarreau]

On Tue, Jul 06, 2021 at 02:06:52AM +0200, Miguel Ojeda wrote:
> > 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.

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

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