aiida-tutorials icon indicating copy to clipboard operation
aiida-tutorials copied to clipboard

👌 IMPROVE: Use consistent tense/perspective throughout tutorial

Open mbercx opened this issue 3 years ago • 1 comments

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

mbercx avatar Jun 25 '21 13:06 mbercx

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.

CasperWA avatar Jun 28 '21 09:06 CasperWA