Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

👌 IMPROVE: Use consistent tense/perspective throughout tutorial #360

Open
mbercx opened this issue Jun 25, 2021 · 1 comment
Open

👌 IMPROVE: Use consistent tense/perspective throughout tutorial #360

mbercx opened this issue Jun 25, 2021 · 1 comment
Assignees
Labels
priority/nice-to-have Nice improvement, but no biggie section/all Applies to all sections type/improve Improving already existing content

Comments

@mbercx
Copy link
Member

mbercx commented Jun 25, 2021

@CasperWA raised a good point regarding the inconsistent use of "we" vs "you" here:

#353 (review)

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 mbercx added type/improve Improving already existing content section/all Applies to all sections priority/nice-to-have Nice improvement, but no biggie labels Jun 25, 2021
@mbercx mbercx self-assigned this Jun 25, 2021
@CasperWA
Copy link
Contributor

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 added a commit to CasperWA/aiida-tutorials that referenced this issue Jun 28, 2021
This was referenced Jun 28, 2021
mbercx added a commit that referenced this issue Jul 2, 2021
Make a thorough pass of the "Organising your data" module:

1. Improving the actual content - mainly minor clarifications.
2. Remove empty lines in code blocks.
3. Try to update the text according to #360.

Co-authored-by: Francisco Ramirez <[email protected]>
Co-authored-by: Marnik Bercx <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
priority/nice-to-have Nice improvement, but no biggie section/all Applies to all sections type/improve Improving already existing content
Projects
None yet
Development

No branches or pull requests

2 participants