On Mon, Jul 5, 2021 at 7:02 AM Willy Tarreau <w@xxxxxx> 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
