search

merely-useful / py-rse

Research Software Engineering with Python course material
http://third-bit.com/py-rse/
Other
246 stars 63 forks source link

Consistency in exercises and solutions #504

Closed DamienIrving closed 3 years ago

DamienIrving commented 3 years ago

There's a couple of things I think we need to make sure we are being consistent about in our exercises and solutions.

  1. Many of the solutions say "the answer should look like this:". Given there are often many possible answers to the same question (from totally different approaches to simply a different choice of variable name), I wonder if we need to soften the language in the solutions to say "the answer may/could look like this:"?

  2. In exercises that ask the reader to edit an existing script (e.g. plotcounts.py) we sometimes give the full version of the edited script in the solutions (rather than just showing the parts that changed) and sometimes fail to give the full version of the script with the question (meaning the reader has to dig back through previous chapters to piece together what the script should look like). I think we need to be consistent and provide the full version with the question and only show changes in the solutions.

Thoughts? Have I missed anything?

(Once we've settled on points of consistency we should add them to CONTRIBUTING.)

cwickham commented 3 years ago
  1. I agree, softer language.
  2. I agree. Is there a way we can leverage the persona Git histories once we have them? E.g. would it be better for the question to link to a version of, say, plotcounts.py in Amira's GitHub repo? Pros: we don't have to include large code chunks in question. Cons: not sure if this adds a maintenance burden for future code/exercise changes.
cwickham commented 3 years ago

And I guess in the meantime (i.e. before we have complete persona Git histories), I'm for putting the full code in the question. That way, it's clear to us, what the starting point is if we are later trying to match to a commit in the Git histories.

joelostblom commented 3 years ago

Agree with both, I think we only need to add the full code to the solutions, right? Not the questions also, so it wouldn't be too intrusive.

gvwilson commented 3 years ago

@joelostblom do you have time to do a pass on this?

joelostblom commented 3 years ago

Yes, what is the timeline? I'ave had some unfortunate personal events to deal with, so behind on everything right now. Should be able to get to this on the weekend or early next week, does that work?

k8hertweck commented 3 years ago

I'm coming back to this now that I'm working on Amira's repo. I'll reference relevant commits in solutions, which will also help keep me on track.

I just checked links and Amira's repo isn't currently included. I'm not sure how to reference this in the narrative, in terms of indicating that it exists as reliable resource. In particular, I'm not sure where to include it (index or solutions? elsewhere?).

DamienIrving commented 3 years ago

@k8hertweck Yeah, it's hard to know how much to reference Amira's repo. If we were writing the book and then not planning on ever doing any updates to the online content, then it would be fine. What I'm a little worried about is that 3 months from now we'll get a PR on the py-rse repo which will change something slightly, and then Amira's repo will be out of sync with the online version of the book...

k8hertweck commented 3 years ago

But there will be print versions of the book, so the references will still match that? I suppose this goes back to #499 , and what our expectations are about updating after publication. I don't think we'll be able to recreate the entire git history when changes happen, but we can at least keep Amira's repo up to date with what we expect the final project will be.

DamienIrving commented 3 years ago

Good point. We should just make Amira's repo consistent with the print book and then deal with any inconsistencies that arise with updated versions of the online book if/when that problem arises (it might not be a problem at all).

joelostblom commented 3 years ago

Sorry for the delay here, I should finish this today or tomorrow.

k8hertweck commented 3 years ago

@joelostblom I've done some work on this already, and some additional work in the slow slog of #560 . Might be worth taking a look. I've also standardized some of the code between narrative and solutions

DamienIrving commented 3 years ago

I also made some fixes to the solutions in #567, which was just merged (although you'll need to use make html to view the changes because https://merely-useful.github.io/py-rse is having some pandoc installation issues and isn't showing the latest version of the book branch in the repo at the moment)

joelostblom commented 3 years ago

Thank you! Do you want me to work of either one of those two branches or wait for both of their changes to be in the book branch?