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

Update guide.md #837

Open
wants to merge 5 commits into
base: gh-pages
Choose a base branch
from
Open

Update guide.md #837

wants to merge 5 commits into from

Conversation

ndilekli
Copy link

@ndilekli ndilekli commented Jun 22, 2020

Naci's SWC homework


Thanks for contributing! If this contribution is for instructor training, please send an email to checkout@carpentries.org with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution.

Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact The Carpentries Team at team@carpentries.org.


Naci's SWC homework
@ldko
Copy link
Contributor

ldko commented Jun 22, 2020

Hello @ndilekli , thank you for submitting an update for the guide. I see you have opened two conflicting pull requests modifying the language of guide.md. Is this pull request meant to supercede #836 ? If you could close one of the PR's, it will inform which one we should review. Also, could you and a short explanation to the PR to explain what your goals for updating guide.md are. This will also help with the review. Thanks again!

@ndilekli
Copy link
Author

ndilekli commented Jun 23, 2020

Goals: 1) Further clarify why Python is a preferred programming language, 2) The existing guide sounded like functions are the most important part of a programming language, I changed the language a little and also provided an explanation why functions are very important (reusability and organization); and 3) Added comments about a common user error when dealing with multiple cells in Jupyter.

@ndilekli
Copy link
Author

ndilekli commented Jun 23, 2020

Copy link
Contributor

@ldko ldko left a comment

Hi @ndilekli , thanks for adding details about the PR changes in a comment; that is just what I had in mind. I have some suggestions on changing some of your proposed wording. I welcome you and others to let me know what you think about them.

_extras/guide.md Outdated Show resolved Hide resolved
_extras/guide.md Outdated Show resolved Hide resolved
_extras/guide.md Outdated Show resolved Hide resolved
@ndilekli
Copy link
Author

ndilekli commented Jun 25, 2020

A question: Am I the one that will need to mark "Resolve conversation" once things look well, or will that be you @ldko ?

@ldko
Copy link
Contributor

ldko commented Jun 25, 2020

Good question @ndilekli :). In most cases it tends to be the maintainers that mark the conversations resolved. I tend to prefer to do that after commits are pushed to the branch/PR that address the conversation when that is relevant. I think the way things are now is fine, but let's see if anyone else from the community has any suggestions (let's give people a day or so), and then if you would go ahead and commit the decided upon changes, that would be great. Thank you very much for participating in the process!

@maxim-belkin
Copy link
Contributor

maxim-belkin commented Jun 25, 2020

let's give people a day or so

No need to wait, I'm here :)

Hi, Naci! Welcome to the Carpentries! I'm a co-maintainer on this lesson. Thank you for bringing this up and working on this.

I like your changes and all suggestions (Lauren's and Samuel's). And it looks like you mostly agree with them. So, because you're new to working with Git, I'd like to clarify that we (maintainers) review proposed changes and propose modifications and contributors (in this case this is you) are expected to update their pull requests if they agree with the proposed modifications. So, if you agree with the proposed changes -- please go ahead and make these modifications. You can do all that from your browser window -- navigate to https://github.com/ndilekli/python-novice-inflammation/blob/patch-2/_extras/guide.md, click the Pencil (Edit this file) icon, make the changes, then at the very bottom of that page describe your changes ("Update based on maintainers' feedback") and commit directly to patch-2 branch.

As it currently stands, I approve of the changes proposed in this PR provided that requested modifications are implemented.

Again, thank you for contributing to the lesson! This is looking great so far! 👍

@ndilekli
Copy link
Author

ndilekli commented Jun 26, 2020

navigate to https://github.com/ndilekli/python-novice-inflammation/blob/patch-2/_extras/guide.md, click the Pencil (Edit this file) icon, make the changes, then at the very bottom of that page describe your changes ("Update based on maintainers' feedback") and commit directly to patch-2 branch.

Hmm... I tried that but the 'Commit Changes" button is disabled.

I also notice that some of the improvements are not yet incorporated to this branch such as:

  • Show that modifying code in an earlier cell requires re-running any
    subsequent cells in order for them to reflect the change.

@maxim-belkin
Copy link
Contributor

maxim-belkin commented Jun 26, 2020

Hmm... I tried that but the 'Commit Changes" button is disabled.

You need to type a title (such as "Update based on received feedback" or something more descriptive -- your choice) -- it should become enabled as soon as you do that.

I also notice that some of the improvements are not yet incorporated to this branch such as:

  • Show that modifying code in an earlier cell requires re-running any
    subsequent cells in order for them to reflect the change.

That was Lauren's suggestion. You need to add it to your branch as I described above. Unless what you're saying is that you did and it doesn't show up. If you did it on your computer, make sure:

  • you added and committed your changes to patch-2 branch
  • pushed that branch to github with git push https://github.com/ndilekli/python-novice-inflammation.git patch-2

@ndilekli
Copy link
Author

ndilekli commented Jun 27, 2020

You need to type a title (such as "Update based on received feedback" or something more descriptive -- your choice) -- it should become enabled as soon as you do that.

I am still having the same problem. I tried with Chrome and Opera.
commit changes disabled
with Chrome and Opera.

@maxim-belkin
Copy link
Contributor

maxim-belkin commented Jun 27, 2020

Looks like you were able to make one update -- 26b9528

Do you remember what you did when you made that change?

@ndilekli
Copy link
Author

ndilekli commented Jun 28, 2020

Looks like you were able to make one update -- 26b9528

Do you remember what you did when you made that change?

I think all I did was to resolve, thinking that would make the suggested changes (by Lauren and Samuel) get incorporated into the version.

@ldko
Copy link
Contributor

ldko commented Jun 29, 2020

@ndilekli , when I go to your branch at https://github.com/ndilekli/python-novice-inflammation/blob/patch-2/_extras/guide.md and click on the pencil icon, at first I see at the bottom that the Commit changes button is disabled. However, I noticed when I click in the file editor (above the "Commit changes" form) and start modifying the text of guide.md, the Commit changes button becomes enabled (even if I haven't entered a title yet). Can you confirm if you have made edits to the guide.md text before trying to commit the changes?

@ndilekli
Copy link
Author

ndilekli commented Jun 30, 2020

@ldko: Very good, the commit (768817a) worked! I needed to make some manual changes in the file so that it would count as a commit, which makes sense in retrospect. I also noticed that there were some broken lines (due to my commenting most probably), which I tried to fix in this manual version as well.

So I guess whenever a conversation is resolved with some suggestions, that in itself becomes a commit, is that correct?

Let me know if you would like me to do anything else.

Thanks, Naci

_extras/guide.md Outdated Show resolved Hide resolved
Co-authored-by: Lauren Ko <lauren.ko@unt.edu>
_extras/guide.md Outdated Show resolved Hide resolved
… the markdown

Co-authored-by: Lauren Ko <lauren.ko@unt.edu>
ldko
ldko approved these changes Jul 6, 2020
Copy link
Contributor

@ldko ldko left a comment

This looks great @ndilekli ! Thanks for working on this section. :)

Copy link
Contributor

@maxim-belkin maxim-belkin left a comment

This contribution brings in some very useful clarifications and improvements! Thank you, Naci!
I'm proposing only a few minor modifications.

_extras/guide.md Show resolved Hide resolved
_extras/guide.md Show resolved Hide resolved
So that our functions can do things we actually care about,
we cover programming concepts such as variables, conditionals,
Copy link
Contributor

@maxim-belkin maxim-belkin Jul 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"So that our functions can do things we actually care about," would've been a great intro to a paragraph describing how to write better functions when we already know how to write simple ones. I think we're one or two steps away from there. Would any of the following fit better the prose of this section?:

To show learners how to write functions that do things they care about, we cover basic programming concepts such as variables, ...

or

To teach how to write functions that do exactly what we care about, we cover basic programming concepts such as variables, ...

Copy link
Contributor

@ldko ldko Jul 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the context of the Instructor Notes and this being just after a statement about what functions are for, I don't really think the prose options above will make for much more of a better fit for the section. However, I prefer your first option to the second (because I don't favor the use of "exactly") if others feel the wording should be changed.

Copy link
Contributor

@maxim-belkin maxim-belkin Jul 7, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(because I don't favor the use of "exactly")

Yeah, I think I agree with that.

Anyways, my point was that we cover programming concepts that we cover not to make our functions do things we care about but to teach/learn how to program in Python. We also learn about functions (which should be added to the list of things we learn). So, here is another possible justification:

To teach how to write Python programs that perform calculations or carry out analysis that we need, we cover most important programming concepts such as variables, conditional statements, loops, lists, functions. We also show how to read data from files and provide input on the command line.

Copy link
Contributor

@ldko ldko Jul 7, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps you are speaking to the point @ndilekli brought up earlier:

the training did not have the feeling like there was a particular effort on the introduction and practice of functions.

In this case, perhaps we should take the emphasis off of functions in the previous sentence as well and say something along the lines of:

This lesson is written as an introduction to Python,
but, its broader purpose is to introduce how to solve problems by developing programs.
By writing lines of instructions to carry out tasks, we automate our work and
enable reproducible results.
To teach how to write Python programs that perform calculations or carry out analysis that we need,
we cover most important programming concepts such as variables, conditional statements, loops,
lists, and functions.
We also show how to read data from files and provide input on the command line.

Copy link
Contributor

@maxim-belkin maxim-belkin Jul 7, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I like this paragraph a lot more: it's easy to read and makes the right emphasis (I'm not sure about "lines of instructions" in the second sentence -- perhaps we need to clearly state that programs are lines of code/instructions -- but that's a minor detail).

* It's easier for novices to learn than most of the mature alternatives,
partly due to its syntax that reads more like a human language.
Copy link
Contributor

@maxim-belkin maxim-belkin Jul 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that we need to explain why [we think] Python is easier to learn [than other programming languages]. However, these bullet points state the reasons why [we think] Python is better suited for teaching basic Programming skills. So, I think it might be better to not explain ourselves right here but move the explanation to the next paragraph. It could start with something like:

That last point above is important. Code written in Python reads more like a human language. Originally, Software Carpentry was teaching programming using Perl. When we switched to Python, we found..."

What do you guys think?

Copy link
Contributor

@ldko ldko Jul 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is fine as-is. I think it will be easier to miss the point if it is moved to a separate paragraph. Also, the lead-in to the list starts with "Explain", so I think it is okay to explain in the list.

Copy link
Contributor

@maxim-belkin maxim-belkin Jul 7, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it will be easier to miss the point if it is moved to a separate paragraph.

I'm not suggesting to move the entire point to a separate paragraph -- only its justification / explanation. Keeping only the main points in the list should make them easier to remember. Those who don't read the next paragraph will miss the explanation(s) but not the point(s).

Speaking of learning... I believe it's the combination of syntax and semantics that makes Python easy to learn: syntax is related to writing proper Python code, and semantics -- to making sense of Python code.

Also, the lead-in to the list starts with "Explain"

To me this serves as a justification to write bullet points as succinct statements rather than sentences. Explanations that we can provide in the list can only be of limited length and I think we shouldn't limit our explanations by the choice of where we provide them.

Do you think the following would convey the message of the last bullet point?

Its easy-to-learn syntax and semantics make it ideal for teaching basic programming skills.

Copy link
Contributor

@ldko ldko Jul 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Taking out from the bullet point the part about Perl as a justification that Python is easier, now we would be stating Python is "easy-to-learn" which I don't like. What makes for Python being "easy-to-learn syntax and semantics"? It may not be considered easy to someone, especially someone who has no reference to other programming syntax. How are the semantics of Python different than other languages?

Copy link
Contributor

@maxim-belkin maxim-belkin Jul 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Taking out from the bullet point the part about Perl as a justification that Python is easier, now we would be stating Python is "easy-to-learn" which I don't like.

I guess my last suggestion was not the best and it confused you. Let me try to better explain my concern.
What we have now in this PR can be represented as:

we do X because:
A
B
C, partially due to D (E)

This last bullet point seems to be overloaded with information a little bit, so I propose to say:

we do X because
A
B
C

C is partially due to D which, in turn, is supported by E.

(A, B, C) together explain why we teach programming using Python.
(C) is the point about Python being easier to learn than other mature alternatives.
I think (C) is important enough to justify spending a paragraph on it.

How are the semantics of Python different than other languages?

In Python "1" + 2 is valid syntactically but not semantically.
In Perl, the same expression is valid syntactically and semantically (result is 3).

In Python "1" + "2" is valid syntactically and semantically.
In Perl, the identical expression ("1" + "2") is valid syntactically but not semantically (result is 0) and syntax of a semantically valid equivalent is "1" . "2".

So, it's always a combination of syntax and semantics that makes a language intuitive or... not-so-much. I think that the closer the syntax and semantics of a programming language to those of (human language + mathematics), the more intuitive it is.

What makes for Python being "easy-to-learn syntax and semantics"? It may not be considered easy to someone, especially someone who has no reference to other programming syntax.

Agreed, this was not the best wording -- we don't have to use it and we can keep "It's easier to learn than most of the mature alternatives". I'm mostly concerned with overloading the last point as I tried to explain in the beginning of this comment.

Copy link
Contributor

@ldko ldko Jul 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps you could do a pull request to submit your changes there @maxim-belkin if you are wanting to reword/reorganize beyond what is presented in this pull request . I think we may have lost @ndilekli :/.

Copy link
Author

@ndilekli ndilekli Jul 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello, sorry that I was out of the loop for a while. I could do another commit, whenever you would like me to. Regarding the Python syntax, I could comment that as someone starting out with Basic, then continuing with Pascal and C, the syntax of Python is indeed much more like reading a text in English. Saying "reads like English" might be an overstatement, but I have seen quite a lot of remarks on that aspect. We might perhaps instead say it is more readable relative to many other programming languages like C and Java. What do you think?

Copy link
Contributor

@maxim-belkin maxim-belkin Jul 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hello, sorry that I was out of the loop for a while.

No worries!

I could do another commit, whenever you would like me to.

Feel free to update the PR whenever you like if you agree with the comments / suggestions. To sum up:

  1. My concern is that we are overloading the last item in the list that explains why we use Python for teaching with information why Python is easier to learn than other (mature) programming languages. Those are related but different topics. So, I propose to move the explanation to the paragraph right after the list. I'm not sure if Lauren (@ldko) agrees with that, so I'd like to clarify this first. If there is no consensus, we might have to leave it as is and discuss this part later in a separate PR or issue.

  2. Please have a look at Lauren's suggestion on how to rephrase the first paragraph in introduction: #837 (comment). You can use it "as is" or make modifications you deem important.

as someone starting out with Basic, then continuing with Pascal and C

Huh, I took the same path with a quick stop at Visual Basic between Pascal and C (it was interesting to observe how Python adopted and extended Pascal's := assignment operator).

, the syntax of Python is indeed much more like reading a text in English. Saying "reads like English" might be an overstatement, but I have seen quite a lot of remarks on that aspect. We might perhaps instead say it is more readable relative to many other programming languages like C and Java.

Sure, that'll work too (I think). This way we won't have to go deep into syntax/semantics stuff.

Thank you, Naci!

Copy link
Contributor

@ldko ldko Jul 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you all agree about splitting off some of the last item in the list to a paragraph that follows, that is fine with me. Please go ahead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants