search

genedan / cl-practitioners-guide

0 stars 0 forks source link

Feedback on the git chapter #16

Closed kennethshsu closed 3 months ago

kennethshsu commented 3 months ago

I got some feedback from Patrick, since he reached out to me privately about git and GitHub.

Hi Kenneth,

I see DataCamp (which my employer pays for) has one course on git and another on github, which I will both take as soon as I find the time. (I had taken a short course on git long ago, but I’ve clearly forgotten everything.)

Everyone is different, but for myself, I think the git section you wrote is probably too advanced for a beginner. If the audience is someone who is unfamiliar with git, I think you need to start way earlier (and ideally have some graphics).

You need to explain why something like git is even necessary or desirable for someone who has already spent years working with Excel files on a share drive with their teammates and never had any real problems. This would help provide context for why all the other things you mention below are useful. For instance, you could discuss how coding projects more commonly have multiple people working simultaneously, or how they more commonly have different versions floating around (many of which may end up discarded or merged into others). I think you actually do sort of mention this, but it’s sort of in a more coder-focused language. You also need to explain that people who use git are typically coders and the files that they’re putting in the repo are generally Python scripts, R scripts, etc. where it’s very easy for the system to compare two files and highlight exactly where they’re different. I think MS Office has made strides in this area recently, but I bet it’s still hard to handle merge conflicts with spreadsheets than it is with R scripts. I think it would also be helpful to analogize every git command to some kind of action that would be encountered in, say, Excel. You do this for a few things (e.g., clone), but it’s hard for me to build a mental picture of what all the others are. (For instance, in the autograph file, I actually made my changes first and then sent the pull request afterwards, which I found very confusing.) In some cases, I suspect there is no single analogous action, and those would need some extra explanation.

Finally, I added my line on top because it was easiest to do so and I wanted this task done! I didn’t think the order of the names mattered.

I'll take this one.