Messages in this thread | | | From | Miguel Ojeda <> | Date | Tue, 6 Jul 2021 02:06:52 +0200 | Subject | Re: [PATCH 13/17] docs: add Rust documentation |
| |
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
| |