aiida-tutorials
aiida-tutorials copied to clipboard
👌 IMPROVE: Use consistent tense/perspective throughout tutorial
@CasperWA raised a good point regarding the inconsistent use of "we" vs "you" here:
https://github.com/aiidateam/aiida-tutorials/pull/353#pullrequestreview-692756589
Since this is rather up to personal preference, we're probably mixing the use of "we" vs "you" quite a bit. @CasperWA indicated that he prefers "you", but here it is claimed that using "we" promotes a personal relationship between the speaker and audience:
https://ux.stackexchange.com/a/57309
I was also a bit more partial to using "you" for instructions, though. This React tutorial (which I think reads nicely) also uses both "we" and "you":
https://reactjs.org/tutorial/tutorial.html
"We" is more used for general statements, like:
- We will build a small game during this tutorial.
- We’ll get to the funny XML-like tags soon.
- This Starter Code is the base of what we’re building.
Or actions from the authors:
- In this tutorial, we’ll show how to build [...]
- We’ve provided the CSS styling so that [...]
- We recommend that you check out the [...]
Whereas "you" is used more for addressing the user:
- You can see what we’ll be building here: [...]
- If you need to review JavaScript, [...]
- If you get stuck, [...]
or suggested actions:
- You can now skip the second setup option, [...]
- We recommend that you check out [...]
- You can close the tic-tac-toe game [...]
Finally, the imperative mood is used for instructions:
- First, open this Starter Code in a new tab.
- [...], open this code in a new tab.
- In Board’s renderSquare method, change the code to pass [...]
It's probably a challenge to write down an unequivocal style guide for this. Maybe someone has already given this some more thought or knows a good resource for this? Going over the material and trying to make it more consistent is probably a good exercise at some point.
I'll try to create two commits for the #342 PR I'm currently working on, one with the corrections in general and one just for this particular point, just to make it clear what changes I'd suggest in a section to align with this sentiment.