Use a consistent voice throughout the tutorials

[sabine]

We need to choose a consistent voice all throughout the tutorials, for consistency's sake and to make it clear how to review the tutorials.

Like...

• do we use a conversational tone that addresses the reader as "you"? Or do we refrain from addressing the reader?
• do we use an academic "we" or a more colloquial "we" when we tell the reader what to do?

[christinerose]

These are great questions, Sabine. Thanks for bringing them up formally in this PR. I was just talking about this with the comms team the other day. So far in my edits, I've been minimizing speaking directly to the reader (so often) and trying to turn "I" into "we" .... as who is "I"? We perhaps is the OCaml Community.

What do you think?

I rather like using the casual language to where the user feels like we're speaking directly to them rather than reading a textbook, but this does need to be kept to a minimum, IMO

[cuihtlauac]

Here are the numbers I get by searching the data/tutorials:

• “I” : 50 occurrences
• “We” : 394 occurrences
• “You” : 431 occurrences

Counts may be off by a couple of units; searching short strings is error-prone. A quick visual inspection of the raw results makes me feel magnitudes should be ok. Updating this doesn't look like a small task.

To a great extent, I consider we're only writing recipes. Addressing the reader at each step seems ponderous to me. However, there are circumstances where it is needed. For instance, to stress tricky matters, give tips or describe hypothetical cases. Like in: “Always use egg and oil having the same temperature. Otherwise, you will ruin your mayonnaise.”

Whether to use “I” or “We”, and in the latter case, which style variant is tricky.

• I prefer reading texts which carry an author's name. I'm not happy when I find an “I” in a text that I can't relate to an actual person.
• Although I can't find good examples to defend “I”, I prefer to leave the door open for such sentences. I'm always very cautious against general prohibition rules.
• BTW, French IPR law, which I believe applies to a couple of the docs, defines the authorship relation as: “perpetual, inalienable and imprescriptible.” This means author names should be provided unless the author does not wish to be named (but it's illegal to ask authors to remove their names).
• OCaml is an opinionated language. Design decisions have been made against mainstream views. Therefore who is denoted by “we” isn't always obvious. Is it the authors of the document, the authors of OCaml or the supposedly existing general view? I try to have this in mind each time I'm tempted to write “we”, and when in doubt about the capability of the reader to get who's referred to, I search for a different wording.

[christinerose]

• I think "I" would make more sense if we did have a single author's name, but these tutorials don't have a specific author (listed, anyway)...so it begs the question, who is "I"?
• I've always read "we" as OCaml users/programmers/community... people who use/teach OCaml.
• Using "we" lends itself for more active sentences: "We prefer xyz" to "xyz is beneficial" (for a quick example). There's a short section on active voice in the Writing Style Guide if you're unfamiliar with the term.

It would be a great undertaking, but it's beneficial to decide these things and then iteratively change them. I'm very excited about this discussion (as an English/grammar geek 😄)

[sabine]

I agree with using "we" in the sense that the text is an amalgamation of a lot of people's work (with more contributors to come).

Individual authors' individual work which requires citations ideally lives in other places and we link to it so that attribution is very clear.

Indeed, we're not stating absolute facts ("xyz is beneficial"), but an opinion between a certain group of people who choose to recommend doing things a certain way in order to benefit from synergy effects around this shared way of doing things. Ideally this aligns with the general view of the OCaml community - when it doesn't, we should try and understand why and if there's more benefit for the OCaml community in keeping the texts or changing them.