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

Remove demotivating uses of "just" #653

Open
wants to merge 8 commits into
base: gh-pages
from

Conversation

Projects
None yet
5 participants
@n2ygk
Copy link

commented Jun 5, 2019

per "How Not to Demotivate Your Learners" usages of the J-word (just) that might be perceived as demotivating have been removed.

I tried to remove "just" only in the demotivating sense of "simply". I also replaced "just" with "only" in one or two instances. I would appreciate feedback. Thanks for the opportunity to contribute.

@murraycadzow

This comment has been minimized.

Copy link

commented Jun 5, 2019

I think this improves the lessons. It reduces the trivialisation (albeit unintended) of the concepts of the sentences, which could be demotivating for learners.

this will fail.
The correct path would be `writing/myfile.txt`.
It is also possible (like with `NameError`) that you just made a typo.
It is also possible (like with `NameError`) that you made a typo.

This comment has been minimized.

Copy link
@murraycadzow

murraycadzow Jun 5, 2019

I would suggest replacing "you made a typo" with "a typo has occurred" to minimise what could be interpreted as accusation.

This comment has been minimized.

Copy link
@maxim-belkin

maxim-belkin Jun 6, 2019

Contributor

I suggest rephasing to It is also possible that there is a typo and all we have to do is find it!.

This comment has been minimized.

Copy link
@n2ygk

n2ygk Jun 6, 2019

Author

In this context, "all" feels similar to "just" in that it implies that it's easy -- which it might not be for a learner.

@maxim-belkin

This comment has been minimized.

Copy link
Contributor

commented Jun 5, 2019

Thank you for the pull request, @n2ygk! 🎉
It actually sparked a discussion among maintainers of what constitutes a proper use of the word "just". I must admit that it does not demotivate me so I will review changes from the point of view of its meaning:
a. We should not be using "just" to imply simplicity/easiness.
b. We should discuss whether we should keep it whenever it implies "only". I'm OK with changing it to "only" but then we need to discuss whether it actually improves the wording.
c. We should either keep it in sentences where its removal makes language harsher or rephase sentences/paragraphs entirely.

@tracykteal

This comment has been minimized.

Copy link
Contributor

commented Jun 6, 2019

Thank you for this PR. It is important to modify how we use language when learners and others tell us that language is demotivating, regardless of whether it is demotivating to a particular individual. We have feedback that language here is being perceived as dismissive, and the ability to address those comments, to create and maintain high-quality, inclusive materials. So, let's move forward on incorporating these updates, as @maxim-belkin suggests in b), replacing 'just' with 'only' as appropriate to maintain clarity, and otherwise removing or substituting it, updating if the validity of the content is affected.

@maxim-belkin
Copy link
Contributor

left a comment

Thank you again for improving our lesson, @n2ygk! Please see my comments above/below. In some of them I asked other maintainers to chime in but feel free to act on others as you feel appropriate.

Show resolved Hide resolved _episodes/01-numpy.md
Show resolved Hide resolved _episodes/01-numpy.md
Show resolved Hide resolved _episodes/01-numpy.md
Show resolved Hide resolved _episodes/02-loop.md Outdated
Show resolved Hide resolved _episodes/02-loop.md
Show resolved Hide resolved _episodes/07-errors.md
this will fail.
The correct path would be `writing/myfile.txt`.
It is also possible (like with `NameError`) that you just made a typo.
It is also possible (like with `NameError`) that you made a typo.

This comment has been minimized.

Copy link
@maxim-belkin

maxim-belkin Jun 6, 2019

Contributor

I suggest rephasing to It is also possible that there is a typo and all we have to do is find it!.

Show resolved Hide resolved _episodes/09-debugging.md Outdated
Show resolved Hide resolved _episodes/09-debugging.md Outdated
Show resolved Hide resolved _episodes/10-cmdline.md

n2ygk added some commits Jun 11, 2019

replace variable named `data` with `inflamation`
I found the use of `data` as a variable name both vague and potentially confusing with the generic meaning
and prefer to use a more meaningful name for the variable.

See, for example, https://www.cs.cornell.edu/courses/cs1110/2018fa/materials/style.php#local-names:
`A local-variable should be a noun phrase that describes the information that it contains.`

Also, https://en.wikipedia.org/wiki/Naming_convention_(programming)#Multiple-word_identifiers:
`A common recommendation is "Use meaningful identifiers."`
Wording improvements per @maxim-belkin review
also add rubber ducking reference.
wording clarifications
- Compare to the previous lesson's string rather than for loop
- grammar plural agreement
- add a TODO item since the diagram doesn't match the code example
@n2ygk

This comment has been minimized.

Copy link
Author

commented Jun 11, 2019

@maxim-belkin I've mostly incorporated the review feedback.

Commits are organized to facilitate cherry picking with the biggest change being that I felt
data was not a good example of a variable name as it could get confused with the generic meaning. However, this requires fixing one of the png diagrams. See TODO inside comments in the source.

I also flagged the container diagram as not matching the code example.

Show resolved Hide resolved _episodes/05-cond.md Outdated
Show resolved Hide resolved _episodes/07-errors.md Outdated
@n2ygk

This comment has been minimized.

Copy link
Author

commented Jun 11, 2019

FYI - I'm going on vacation for 10 days so please don't take my silence as lack of follow through....

n2ygk added some commits Jun 21, 2019

@n2ygk

This comment has been minimized.

Copy link
Author

commented Jun 24, 2019

@maxim-belkin: I think I'm done. Please approve as you see fit. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.