Review Ticket: Jupyter Notebooks as Argument

acrymble commented 5 years ago

The Programming Historian has received the following tutorial on 'Jupyter Notebooks as Argument' by @quinnanya. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/lessons/jupyter-notebooks

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

@walshbr will act as editor for the review process. His role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. He will first read through the lesson and provide feedback, to which the author will responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. He will make an announcement on this thread when that has occurred.

He will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me or @walshbr. You can always turn to @amandavisconti if you feel there's a need for an ombudsperson to step in.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our Ombudsperson (@amandavisconti). Thank you for helping us to create a safe space.

walshbr commented 5 years ago

@quinnanya - 👋 Looking forward to reading this! I anticipate being able to get an initial read to you back by the end of next week. I'll let you know if anything changes, and let me know if you have any questions about the process.

Also, for what it's worth, we're going to use this editorial process to help familiarize two newer members of the editorial team with the process and workflow. So @rivaquiroga and @JoshuaGOB will be shadowing along as I work with you.

quinnanya commented 5 years ago

@walshbr - I've got a couple days' breather in between DH and ACH and was wondering if it'd be desirable, problematic, or neutral if I were to tweet about this and encourage feedback on it? A lot of people seemed interested in it when I've mentioned it before, and there's a couple projects where I've been pointing it preliminarily to people who are new to Jupyter notebooks but want to use some of the ones I've put together.

But I can also see having a ton of feedback from all over being a major pain for you folks to synthesize as editors. Thoughts? Thanks!

walshbr commented 5 years ago

Hey @quinnanya - we’ll need two formal reviewers, but I haven’t started assembling names. If you had suggestions I’m happy to reach out to them so that I can give them a sense of what is involved with a review and what our expectations are. Beyond that, I think it’s fine if you wanted to circulate the link with a request for general feedback. We can treat that as supplement to the formal reviews. Though it’s also a question of how much feedback you want to deal with!

Before you do circulate, though, I had a few suggestions for generic changes that might help bring it a little closer in line with the format of some of our other lessons. And a few other technical tweaks to offer. We’ve got a skype call this afternoon to discuss, so I should be able to comment on the thread here by the end of the day tomorrow. I’m glad you’ve submitted this - I think it’s great and very useful.

walshbr commented 5 years ago

Hey @quinnanya - this looks great to me. I think it will be a useful addition to the slate of lessons, and I'm glad that you've taken the time to put it together! I especially liked all the provocations that you offered for how notebooks might be used. I think this will help people think in new ways, and I liked the generous citations you offered for other examples so that folks can find their way.

I think there are a couple things to address before we send the lesson out for review. I have a couple structural suggestions below, a few technical points, and then a few line comments. Fair warning - I’ll give the piece another read before sending it for review after you send in revisions. I didn't go too far in depth here just because it might change as you restructure the middle. If you're able to address those structural recommendations, though, I think any further comments from me will be pretty minor once I get the revisions back from you.

Let me know if there is anything here that you want to talk further about before revising. And when you have a chance to look at your schedule let me know what a reasonable timeline will be for you. We can be pretty flexible, but putting a tentative date on the calendar lets me know when to check in to see how things are going.

Substantive points

One thing that we talk a lot about internally on the board is how to make our lessons distinct from documentation. In other words, if X software tool already publishes their own documentation, why do we need to publish our own version of the same? What makes what we're doing different? I think as it stands, the beginning and ends of the lesson offer really compelling scholarly framing for jupyter notebooks. The middle feels a bit closer to documentation (though still really useful documentation at that). I’d focus on trying to make the middle portion of the lesson more engaged in the same kind of thinking and approach that you do at the beginning and end.

Most of our lessons accomplish this generic move by framing themselves around a particular case study. For example, the Audacity lesson gives a podcast as the product a reader will have produced by the end. And the steps and interface instructions are produced in the service of getting you through to that end product and reflecting along the way.

I think you actually have the makings of what could be a good case study in the list of four uses in paragraph 60. I’d suggest you take one of those four use cases and develop the example notebook that you work with in that direction. The content of the lesson itself might even take you from nothing (you’ve opened a new notebook) to building out an example pedagogical notebook for jupyter notebooks, perhaps copying and pasting in material that describes what the different sections of a notebook and its functions are as it grows in length. That clear direction (take this from the lesson and move it to the notebook) might also help to distinguish the lesson from the example notebook a little bit more by more clearly defining how the two interrelate. Jumping back and forth between the lesson and the notebook might get a little confusing, so I think taking care to negotiate the user through the different windows and interfaces will be useful.

That’s all to say that I think the bulk of the walkthrough for the notebook is great and can be kept pretty close to what it is - just bring out the narrative layer a bit more. I see that there is a narrative there, so I think foregrounding the path through will help tie the whole thing together around one of the topics you offer.

Related to the narrativization of the piece as a whole, I’d think about how you can conclude the lesson a little further. Either by offering thoughts on next steps, reflections on what they’ve learned, etc. The scaling up computation could actually be a good way to do this, and in that case I think it’d just need a sentence or two framing them as concluding thoughts. Wouldn't require much work.

At times it feels like your discussion might warrant some screenshots when you’re describing the interface of the notebook. While it’s a little tricky since you’re expecting people to have a notebook of their own that they’re running, it probably would help to show them screenshots guiding them through what they’re looking at. We try to minimize screenshots for sustainability purposes, but they’re still fine when they’re necessary.

Technical

It looks like there are a couple issues in the metadata that are preventing the lesson from rendering properly. Some of the YML keys had “-tbd”, but they needed a space after the dash. I took care of those for you.
I updated the table of contents syntax, which looked like it was a hangover from the template we gave you (also put a note in for us to update that template!).
[ ] p. 21 - missing images - it looks like the image you linked to isn’t showing up. Instructions for the syntax are here (it’s different than normal markdown in this case) - https://programminghistorian.org/en/author-guidelines#including-images. I can help if you run into issues, but since you have the image in a folder in assets already it looks like if you just use the figure syntax you should be good.
[ ] p 27 - to get the link to the lesson to work, the path should be “/assets/jupyter-notebooks/ph-jupyter-example.ipynb”

Small points

[ ] The learning goals and topics covered them as you have them here might better work as a bulleted list
[ ] p. 16. Is it possible to install jupyter notebooks without anaconda (say if you already have Python installed)? I think it’s worth saying either way re: whether this is the only way.
[ ] somewhere around p. 39 - worth mentioning that the reason for the strange outputs (at least in some cases) is that your code might require running sequentially. if one piece of code produces a variable that is needed later, etc.
[ ] p. 60 - you say “three uses” but then list four things
[ ] p. 64 - in this and the following sections, the structure looks to be an explanation followed by an example or two. Sometimes those examples aren’t rhetorically contextualized. I think it’s just as easy as saying “For example……”. The first one with McEleney’s work is the one where this was most noticeable, but worth checking the others too.
[ ] p 74 - “Jpyter Notebooks”

quinnanya commented 5 years ago

@walshbr Wow -- thanks so much for both the high-level and close-read feedback! Happy to work on implementing both. Next week is going to be a lost cause because of ACH, and then there's post-conference catch-up, but how about I try to get you the next revision on August 9th?

walshbr commented 5 years ago

Of course - thanks for writing! August 9th seems fine - I think usually we tend to ballpark about a month for the revisions and another for reviews anyway. I made a note to check in if I haven't heard anything by the 9th. I'll also be at ACH along with a bunch of SLab folks - hope to see you there!

quinnanya commented 5 years ago

@walshbr I'm still really hoping to get this done this week, but I've come across what I think is a much better narrative thread for it (based on a true story of fanfic metadata wrangling), so I'm doing some non-trivial reworking of the example. Next Friday, worst case!

walshbr commented 5 years ago

That sounds great! Thanks @quinnanya

quinnanya commented 5 years ago

@walshbr I've totally rewritten the description so it's a narrative, made various smaller tweaks based on the feedback above, added new example data, replaced the example notebook, and added some more screenshots. Happy to do more if there's something else it needs before going out to reviewers, just let me know!

https://github.com/programminghistorian/ph-submissions/pull/255

walshbr commented 5 years ago

awesome thanks, @quinnanya! I'll take a look at this ASAP, hopefully in the next week or two, and let you know where it stands.

quinnanya commented 5 years ago

@walshbr I thought I was able to resolve the conflicts, but now I'm getting a Jekyll page build error message, which puts me in the realm of "totally stumped". If you have any tips (or can see what might be going wonky), advice would be wonderful!

walshbr commented 5 years ago

Fixed @quinnanya! The problem wasn't actually with your work - since we have multiple lessons on this repo, if an issue comes up with a different it will sometimes mess up other lessons in progress re: build errors. I put in a ticket to address this particular one. But yours looks like it's passing now.

quinnanya commented 5 years ago

@walshbr Whew, that's a relief! Thanks!

walshbr commented 5 years ago

@quinnanya just a note to say that I haven't forgotten this - I've been slammed with the start of classes, but I'll try to get to this in the next two weeks. I apologize for the delay!

quinnanya commented 5 years ago

@walshbr No worries! If it's possible, it'd be great to know what URL it'd be published at (would it just be /lessons/jupyter-notebooks?) so I can cite it in something that's due 9/15.

@jerielizabeth and @diyclassics mentioned being up for reviewing it, if/when you need reviewers.

walshbr commented 5 years ago

Thanks so much - they'll be great reviewers!

And thanks for your patience. The slug can be whatever we want. https://programminghistorian.org/en/lessons/jupyter-notebooks-as-argument seems fine to me, since it would mirror the title of the lesson.

walshbr commented 5 years ago

Hey @quinnanya - so sorry again that it took me so long to get this back to you. This looks great! I think the case study works really well, and you do a great job of showing what you can do with notebooks. The discussion is really wonderful and pushes it far beyond just being documentation. I had a few really tiny things below. Really, I don't think any one of them is asking for more than a sentence. The two biggest things I noticed were that there was an error in one of the filenames and that the image syntax wasn't working correctly. So I would just, first and foremost, take a look at the download links (for the csv) and images to make sure they still look as intended. I went through the lesson and tried to address all those for you. The other things belwo are all small enough that, while I'd still like to see them addressed, I don't think we need to wait to send it out to the other reviewers to check out. So I'll get in touch with the two folks you suggested, make sure they know the deal with reviewing, and ping back here when they've committed to the timeline. Whenever you get around to taking a look at the following points (they're really small) maybe just drop a note in the ticket here so that folks know you've updated the lesson to its most recent form. Let me know if you have any questions!

[x] paragraph 4 in the list of lessons using notebooks “,and” - just a space after the comma
[x] Prerequisites - should probably mention the version of jupyter notebooks the lesson is running.
[x] p. 11 - might be good to gloss what the term “macros” means.
[x] We put the superscript number of a footnote after the punctuation mark, not before it. So I’d just do a search through for the few notes you have to make sure that you’re following that protocol.
[x] p. 21 - “You want to find out what the distribution of publication and updated dates is throughout the week, and whether there’s any correspondence between the day of the week the story was published and the day of the week it was last updated.” - I found this sentence confusing. Is this setting up the research question to come (with the ‘you want to find’ bit)? If so, it might be helpful to just say “In the lesson to follow we will explore the distribution of X and whether Y.” Also - it’s probably not super important, but I was immediately wondering what the rating system actually meant. Are those ratings about quality of the stories?
[x] Everything is currently in the assets folder (which is where datasets and things like that go). So I moved the images out to the images folder and left the datasets and example notebooks in the assets folder. Also required implementing our figure syntax - {% include figure.html filename="IMAGE-FILENAME" caption="YOUR CAPTION USING \"ESCAPED\" QUOTES" %} - for images. That’s just an FYI - I was shifting several things around, so you might just give a glance at the points where you link images or things to download and make sure that they all work as expected. I think I got it all though!
[x] p 26 - might be worth mentioning that the window will look different if you’re launching the navigator not through anaconda. That’s how I run it, and I’ll just make a note of any inconsistencies. If there aren’t any, you could just say that the initial screen will look different but all other things will be the same.
[x] p 29 - on my computer, when i launch jupyter notebook from the terminal, the notebook actually seems to just launch inside whatever folder I’m in. So if I launch it right after opening the terminal it would be in my users folder, but in this case I had made a new folder for the lesson’s work. So it launched inside the empty directory I had made.
[x] FYI - for the code blocks using three back ticks with the code all on its own lines instead of two will allow it to respect line breaks and be easier to read. I went through and adjusted all of these for you.
[x] p 38 - “Use the dropdown to change it to a Markdown cell.” - probably not immediately clear to a new user which dropdown you mean. It’s the only one on the screen, I suppose. But you might just say something like “there is a toolbar for jupyter notebook functions at the top of the window. select the dropdown that reads ‘code’ there to X”. Perhaps also useful because you talk about that toolbar later on.
[x] After p 49 - I might add a sentence to clue the reader back into the fact that you’ve returned to real commands to be run, whereas the previous couple moments were hypothetical.
[x] p 51 - maybe worth mentioning that the cell that will run is the cell currently selected?
[x] p 62 - i think you need to add a sentence telling the reader to run that cell now after they paste it.
[x] p 70 - again i would just remind people that they have to run the cell to execute the code and that pasting it in won’t actually run the Python piece until they hit that button. might also be a good moment to point out that this will take slightly longer, but they can watch the asterisk/number change to see when it’s done (that’d just reinforce what you’ve already taught them).
[x] p 81 - claps
[x] second bullet under “links” might want a period at the end to conform to the structure of the first bullet point.

walshbr commented 5 years ago

Just a note that I also touched base with @jerielizabeth and @diyclassics to confirm they were still up for reviewing. They are good for it. I'll make a note check back in the second week of October to make sure that things are moving along. @quinnanya - if you do happen to make the superficial changes I suggest above just ping the reviewers here so they make sure they are looking at the updated text. Let me know if you all have any questions!

quinnanya commented 5 years ago

@walshbr Thanks! I've made those changes (I think I covered everything?) and sent a pull request, though I'm not sure what's causing the problem for automatic merging. (@jerielizabeth and @diyclassics stay tuned for an updated version soon!)

walshbr commented 5 years ago

@quinnanya take a look at the file now? I resolved the six conflicts that appeared, but it'd be great if you could double check these places in the text to make it reads as you want. I think I got them to what you had in mind.

## Using Jupyter Notebooks for research

### Launching Jupyter Notebook

### Uploading the example data

“Returning to our example, next add another new code cell, and paste in the following code:”

“Run the cell with the code th”

“After you run this code,”

quinnanya commented 5 years ago

@walshbr Thanks! It all looks good.

diyclassics commented 5 years ago

General points

NB: Editing while using Jupyter notebook server 6.0.1 with Python 3.7.4
Excellent coverage, more or less reflecting my (daily!) experience writing, teaching, etc. with notebooks, inc. several journal/conference submissions with corresponding repos with notebooks.
One topic not mentioned in the article or in the comments below that I would consider essential would be an explanation of magic commands and especially the cell magic command %%timeit for measuring a cell’s execution time; https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-timeit
One thing to consider—the tutorial occasionally veers into “Anaconda tutorial” or “Python tutorial” (either Python environment or Python programming): in the end I think it works fine and honestly to some degree it is simply out of necessity—e.g. you have to run some code in the notebook. Still it may be worth a reread to ensure that the sentences that are not directly about Jupyter are essential or whether they should be made parenthetical or even moved to a footnote.

diyclassics commented 5 years ago

Specific points (keyed to the text)

[x] Abstract: Should mention early that Anaconda is not required for running Jupyter; or maybe generalize at this point, i.e. not mention Anaconda specifically
[x] “The reality of current academic publication guidelines…” It is often possible to publish notebooks (perhaps without full text) as supplementary materials. The tutorial hints at this direction further down at “This stands in contrast to the more common current…”
[x] “Jupyter Notebooks have gained more traction”—While I agree that notebooks have a solid pedagogical presence in DH, I’m not sure that I’d say more traction—at least that’s my impression (and I’m not sure how I’d quantify or establish it one way or the other). They seem common in research settings.
[x] “(Julia, R, and Python)”—Why not in JuPytR order?
[x] “You can close the prompt about creating an Anaconda Cloud account; you don't need an account to work with Anaconda.”—Parentheses?
[x] “If you launch Jupyter Notebook from the command line, it will display the contents of the folder you were in when you launched it.” This is true of the bare jupyter notebook command; but you can directly launch notebooks with an additional argument, e.g. jupyter notebook example.ipynb
[x] “You can either do this in your usual file management interface”—may be helpful to clarify that Jupyter is also a file management interface as well as a menu-and-toolbar UI inside the browser (like, e.g., Google Docs)
[x] “Click on "Python 3”—Is it worth explaining the idea of the kernel at this point in the tutorial? that is, at the point at which a kernel is launched.
[x] “you can no longer undo edits”—This is not the case with the Mac version (and I think this has been the case, i.e. not related to v. 6.0.1); each cell retains its own undo history. Not sure if there is an upper limit. Note that in a Markdown cell you have to be in the Markdown editing mode; i.e. undo does not work on rendered Markdown.
[x] Option+Enter on Mac (Alt+Enter on Windows, I think—don’t have a Windows machine here to check) exits editing mode and creates a new blank cell below.
[x] “If you are working on a notebook that you want to share”—worth explaining that the exclamation point is used for executing command-line commands?
[x] “it's still important to save your notebook” True, though autosave is the default setting.
[x] “You can also download”—worth mentioning nbconvert (https://github.com/jupyter/nbconvert)?
[x] “Some scholars post these notebooks on GitHub”—I would mention that GitHub renders (non-interactive) version of the notebooks; so does nbviewer (and often more quickly and more reliably)
[x] “Dobson”—Dobson p. 39-41 may be worth citing specifically in this tutorial, esp. for the part on p. 40 re: “notebooks are theory”
[x] “There are many digital humanities "intro to Python”—capitalize “Intro”?
[x] “MyBinder”—why not https://mybinder.org/; in case the specific deployments are of interest though, cf. https://binderhub.readthedocs.io/en/latest/known-deployments.html
[x] “Because the data…”—there are ways around this, but they may fall under “advanced”; cf. https://github.com/diyclassics/axelson, spec. the postBuild file that allows spaCy models and CLTK corpora to be “included” in the repo, i.e. downloaded to the Binder image at runtime.
[x] ## Converting existing Python code—been meaning to try this, perhaps worth a look/mention: https://pypi.org/project/p2j/
[x] “the use of Jupyter notebooks for collaboration”—been meaning to try this too: https://www.reviewnb.com/

quinnanya commented 5 years ago

@diyclassics Thank you so much for the detailed and thoughtful review! TBH, I learned more than a couple things from your comments! Will work on revising it (but I'll keep the updates local for now to not mess things up for Jeri).

walshbr commented 5 years ago

Thanks for the generous review @diyclassics!

@quinnanya - yep please keep any edits local for now. @diyclassics also mentioned that he has a PR that corrected some typos ready to go, so be on the lookout for a pull request to that effect. I think it's ok to merge that in since the typos might be things @jerielizabeth would catch anyway.

And @jerielizabeth just let me know if you needed more time for your review. I had it written down to check in around October 10th anyway, so consider this that check in :)

jerielizabeth commented 5 years ago

I'm on track to have my review in by the end of the week! Thanks for the patience!

jerielizabeth commented 5 years ago

General points

I also think this looks great and will be a valuable addition to the Programming Historian lessons! Thank you for tackling such a large topic and for doing it so well!

I did notice that the level of technical skill assumed varies depending on your audience - most of the lesson is geared toward people who are starting out, but some of the asides to those interested in using Jupyter for teaching assume much more technical skill (as one would expect.) It may be worth considering keeping all the adaptations for teaching to the teaching with Jupyter section. Then you have a consistent skill level that you are speaking to.

I also appreciate the plug for using Jupyter for publishing :D Overall I think the extending sections are great - I think it is good to emphasize that it is a format that can be used in a wide variety of settings and for a wide range of problems.

I also ended up using Jupyter 6 for testing as part of the review - that is what Conda pulled from by default. Would users need to do anything in particular to get version 5.7.8 that you used?

Specific points

I second @diyclassics feedback so I will take care not to replicate :)

[x] 16 - I would add data analysis as one of the potential places where the notebooks are particularly useful (and fits your example here.)
[x] 17 - One additional interface for Jupyter is Hub … I’m not sure I’d mention here b/c that would muddy the waters, but for people interested in using it for teaching, it might be worth pointing to.
[x] 22 & 23 - These paragraphs felt out of place to me. I would suggest moving them around pp. 32 or 44. Also, I am not sure that the lesson made it to looking at the correspondence between publication and update dates.
[x] 27 - if working with anaconda from the command line do you need to activate an environment? ( i work with Conda rather than Anaconda, so unsure how much Anaconda just handles)
[x] 29 - well …. visual code studio has jupyter plugins, just to be complicated. :) Not recommending mention it, but maybe soften the “only”
[x] 39 - do you want to teach them the keyboard shortcuts? :D esc m to turn a cell to markdown; esc a to add a cell above. Return to enter “edit” mode on a cell.
[x] 43 - shift + return also runs a cell on a Mac. can also navigate with the up/down arrows. apparently i'm addicted to the keyboard shortcuts.
[x] 44 - abrupt transition here.
[x] 45 - shift + return also automatically adds a new cell.
[x] 52 - I’d put a warning about the error nearer to the code block here - I left the lesson here to go googling to figure out what had happened.
[ ] 61 - I don’t think you need second import (from dateutil.parser import parse)
[x] 68 - You may need to warn readers to mind the tabs with that paste.
[x] 71 - I would suggest a few inline comments to explain what the different lines are doing, just for that newer to Python user who will probably be overwhelmed by the code block here. Also, do you want to include a view of the CSV files so that people can see where the started and where they ended?

Again, overall I think this is great! And I anticipate seeing more Jupyter converts as a result of this lesson :D

walshbr commented 5 years ago

Thanks @diyclassics and @jerielizabeth! These comments all make a lot of sense to me. @quinnanya - did you have anything you wanted to discuss before implementing them? Also note that @diyclassics put together a pull request here - https://github.com/programminghistorian/ph-submissions/pull/265 - that fixes some typos. Might be good to merge that in with what you have before you do too much revising. Let me know if I can help with anything. And how does one month for revisions sound? So aiming to get things back by November 11th?

walshbr commented 4 years ago

@quinnanya - just checking in on this at it's now the appointed time. Did you need anything else from me as you work through these revisions? Did you have a timetable in mind for turning them around? No worries if you need more time to revise - just let me know and we can set a new date if need be.

quinnanya commented 4 years ago

@walshbr Fear not, 17 hours remain in the window of the appointed time! 😁 Seriously, though, almost done. All my kids have the day off, so push come to shove it may be pretty late in your day, but I'll have a PR coming today.

walshbr commented 4 years ago

Ha! That all sounds great. No worries on timing - I'll hope to get to it in the next week or so and let you know if anything comes up once you get it in.

quinnanya commented 4 years ago

Okay, just sent the pull request, thanks to some help from the YMCA Childwatch! (Editing Jupyter notebooks is a workout, right?) 🏃🏼

@diyclassics - I put %%time/%%timeit stuff under “Scaling up computation with Jupyter notebooks”. I’ve never used them myself, so I had to do a little reading. Let me know if I’m missing something big? I also added it to the example notebook.

Also, with the Dobson quote — would you mind checking if this actually is on p. 41 (final quote at the end of the lesson)? My Kindle version doesn't have page numbers, but from your comment I'm guessing you've got the paper copy?

@jerielizabeth I didn't know about those keyboard shortcuts! Thank you!

diyclassics commented 4 years ago

Happy to check—the Dobson quote is on page 40. (Also, the 39-41 range listed earlier is correct.)
The %time etc. magics look correct as well.

quinnanya commented 4 years ago

@diyclassics Thanks! (The earlier page range was from you. 😉) I fixed the page number for the final citation, and it looks like it's reflected in the pull request now too.

walshbr commented 4 years ago

Sounds good thanks!

walshbr commented 4 years ago

@quinnanya - this looks great to me. I fixed a couple syntax things in the version of record here. To my eye, the only remaining issues are these -

[ ] p 44 - “To leave editing mode and “run” this cell (for a Markdown cell, this doesn’t do anything, just moves you further down the notebook)” - Rather than saying it doesn’t do anything, I might just note that running a markdown cell will parse the markdown and render it as styled text.
[x] p 46 - “To add a new cell, click the plus button in the toolbar (or use the esc + a keyboard shortcut).” - The ‘a’ shortcut actually makes a new cell above the selected cell on mac at least. b is the shortcut for below.
[ ] p 55 - a note to myself to make sure that the font awesome icon renders on the live site (we don’t have FA on the ph-submissions staging site, so it’s not rendering yet).
[x] 53 - (If you try running this code, you’ll see an error: “ValueError: time data ‘1/7/18’ does not match format ‘%d/%m/%Y’”. Don’t worry – we’ll debug this next.) - This error will actually be different because the imports haven’t been run yet. You won’t get the ValueError until you fix the NameError from not importing first.
[x] p 67 - “Delete the last line of the code block, and replace it with:” - Need to specify that this should all be indented I think? Pasting by default only indents the first line on my computer at least.
[ ] p 71 - “After you run this code, you will have a new file, ph-jupyter-notebook-example-dayofweek.csv, with your data in the format you need for analysis.” - I might be missing something, but to my eye it looks like this doesn’t actually create the file you mention.
[ ] p 82 - This example pedagogical notebook is a hybrid of some of the pedagogical approaches described above. - does it exist?

If you could address those I'll work on the remaining editorial checklist things. Let me know if you have questions!

walshbr commented 4 years ago

Ah and I'll need one-sentence bios and orcid (if you have them) for the three members of the team. (I'll check in about anything else I'm missing as I go along @quinnanya). You can drop that biographical information here.

quinnanya commented 4 years ago

Thanks, @walshbr! Sending a pull request in a sec. A couple responses...

p 44 - Rather than saying it doesn’t do anything, I might just note that running a markdown cell will parse the markdown and render it as styled text.

The thing is, it's already parsed and rendered at this point. Nothing changes, it just moves you further down the notebook.

53 This error will actually be different because the imports haven’t been run yet. You won’t get the ValueError until you fix the NameError from not importing first.

I've tweaked the wording here; was trying to figure out where to put this warning so it's close enough to the code to catch the attention of the kind of user who wants to jump ahead, before they get too distracted. Does that do the trick?

p 67 indentation I've added the indentation to the code itself, and stuck in a parenthetical about checking the indentation
p 71 new file Ack, good catch. I copied and pasted the commented code from the notebook so there'd be one set of comments (to make it easier for translators) and forgot the notebook version doesn't create an output file. Fixed that, I think.
p 82 does it exist? I hope so! It's in the assets folder, and I realize I got the path wrong. Tried to fix it based on the image above, let me know if that works?

walshbr commented 4 years ago

Ok! That all sounds good to me. I'll check out the PR in a second.

diyclassics commented 4 years ago

I'll need one-sentence bios and orcid

PJB: ORCID 0000-0003-2158-866X. Postdoctoral Fellow for the Quantitative Criticism Lab at the University of Texas at Austin; Latin tools developer for the Classical Language Toolkit.

walshbr commented 4 years ago

@quinnanya - i had two issues with the updated code block: mixed tabbing and spaces for indentation and then it never actually called csvwriter to write the rows. I think I corrected both of this things in this commit (line 292 was the only new line I added - the rest was just normalizing the tabbing). The rest of your changes looked good. If that works for you we should be good to go once I get a bio for each of the authors @quinnanya.

quinnanya commented 4 years ago

Sorry for the delay on this one! I've got all three bios on my end:

Quinn Dombrowski is the Academic Technology Specialist for the Division of Literatures, Cultures, and Languages at Stanford University, and works on non-English digital humanities. Tassie Gniady is the manager of the Cyberinfrastructure for Digital Humanities and Creative Activities (CyberDH) at Indiana University and David Kloster works with her as a programmer/analyst. They teach workshops and consult on a variety of projects involving text analysis in addition to providing support for 3D digitization and other eXtended Reality endeavors.

Quinn: https://orcid.org/0000-0001-5802-6623 Tassie: https://orcid.org/0000-0001-8693-3677 David: https://orcid.org/0000-0001-8577-8409

walshbr commented 4 years ago

Thanks @quinnanya. All three bios will exist as separate entries in our yml file, so how about this?

Quinn Dombrowski is the Academic Technology Specialist for the Division of Literatures, Cultures, and Languages at Stanford University, and works on non-English digital humanities.

Tassie Gniady is the manager of the Cyberinfrastructure for Digital Humanities and Creative Activities (CyberDH) at Indiana University.

David Kloster works with Tassie Gniady at Indana University as a programmer/analyst for Digital Humanities and Creative Activities (CyberDH).

The third was the one I was least sure of segmenting out like that. If you can confirm that works for you (and sounds like the one or two commits I sent you were fine) then we should be good. If not, just let me know if you have different language for David's bio?

quinnanya commented 4 years ago

@walshbr Thanks! Looks fine to me, but I'm double-checking with Tassie. Will let you know soon!

quinnanya commented 4 years ago

Okay, here's a tweaked version:

Quinn Dombrowski is the Academic Technology Specialist for the Division of Literatures, Cultures, and Languages at Stanford University, and works on non-English digital humanities.

Tassie Gniady is the manager of the Cyberinfrastructure for Digital Humanities and Creative Activities (CyberDH) at Indiana University.

David Kloster works in the CyberDH group at Indiana University as a programmer/analyst.

walshbr commented 4 years ago

Thanks @quinnanya! We should be good to go to publish this then. @svmelton, as I understand the semi-new process, at this point I'm supposed to give you a list of all the changed files for you to PR over to the other repository. Let me know if you have any questions? And if you want to tag me on the PR I'll give it a look over just to make sure I didn't miss anything either. I'll also put together the tweetbot tweets at that time.

Here are the lesson files you'll need:

lesson file - /lessons/jupyter-notebooks.md
images folder - /images/jupyter-notebooks/
assets folder - /assets/jupyter-notebooks/
gallery image - /gallery/jupyter-notebooks.png
gallery original - /gallery/originals/jupyter-notebooks.png

The following author bio is for adding to the /_date/authors.yml file on the other repository:


- name: Quinn Dombrowski
  team: false
  orcid: 0000-0001-5802-6623
  bio:
      en: |
          Quinn Dombrowski is the Academic Technology Specialist for the Division of Literatures, Cultures, and Languages at Stanford University, and works on non-English digital humanities.

- name: Tassie Gniady
  team: false
  orcid: 0000-0001-8693-3677
  bio:
      en: |
          Tassie Gniady is the manager of the Cyberinfrastructure for Digital Humanities and Creative Activities (CyberDH) at Indiana University.

- name: David Kloster
  team: false
  orcid: 0000-0001-8577-8409
  bio:
      en: |
          David Kloster works in the CyberDH group at Indiana University as a programmer/analyst.

Let me know if I'm missing anything?

svmelton commented 4 years ago

Thanks, @walshbr! I'll work on this during the week.

svmelton commented 4 years ago

Just a quick note for transparency: I removed the link to Sarah McEleney's project because it looks like it's no longer on GitHub.

Also, it looks like the link to the R example is broken, and I can't spot an alternative in the repo. Happy to either replace or delete the reference. @quinnanya @walshbr

walshbr commented 4 years ago

Just making sure you saw this @quinnanya - let us know if we can do anything to help. Looking forward to seeing this go live.

quinnanya commented 4 years ago

@walshbr Oops! Didn't realize I had the chance to do something about it; just sorta shrugged and figured "ah, that's too bad". Should be able to get updates by tomorrow!

programminghistorian / ph-submissions