Binderhub: BinderHub SciPy 2018 paper

[choldgraf]

Hey all - let's use this issue to create our Scipy 2018 paper / talk!

This paper is now published! here's a link and here's the DOI: 10.25080/Majora-4af1f417-011

Here are some details from when we were planning this:

Things you could help with (in order from most to least pressing)

Things to do for the Binder @ SciPy presentation

We are presenting Thursday at 4:30pm (link)

• [x] Find a Binder repository that highlights reproducible publishing (slide). (could be the LIGO project, just wondering if something new has come out worth highlighting)
• [x] Last section on running / sustaining an open public service (mybinder.org) (slide)
• [x] Final slides on what's next for Binder (slide)
• [x] General run-through, comments, etc!

Finished items

• [x] Create an outline of slides to present @ scipy
• [x] Add content to the slides
• [x] Help respond to reviewers in the paper pull request
• [x] Add references to the paper
• [x] Give a high-level pass to make sure we're not missing something in the "big-picture"
• [x] Make sure we balance technical detail / high-level ideas properly
• [x] Think of / add other future directions for Binder
• [x] Small improvements to wording, sentence structure, etc
• [x] Copy-edit
• [x] Add your email/affiliation in the authors list

Links

• repository with rST version of paper
• latest PDF of the paper
• original scipy pitch (issue #422)
• collaborative draft of this paper no longer under development

link to the full instructions.

Work plan

• [x] Come up with a workplan for putting together the paper
• [x] Finalize first draft of the paper (see this repo)
• [x] [make a pull request on the scipy proceedings repo](https://github.com/scipy-conference/scipy_proceedings) (Due May 23rd)
• [x] Round of feedback from reviewers
• [x] Come up with a workplan for putting together a talk
• [ ] Make the talk
• [x] Submit (6 weeks later)

cc @mpacer @minrk @Carreau @jzf2101 @yuvipanda @willingc @betatim

[jzf2101]

@choldgraf I don't see a stylesheet .cls equivalent- I don't know what the .rst equivalent would be.

Also, I think we should compile references we can reuse. @willingc and @yuvipanda 's slides and the writeup from FAT* could be a good start.

[choldgraf]

That's a good idea!

Though I think that this one may be a bit different, as it's meant to go into a bit more technical detail about binderhub/kubernetes/etc (at least, that's how we presented the paper submission).

[willingc]

The SIAM paper is also a good resource. As an FYI, there's a new Google Docs theme for Jupyter that is similar to the one for Keynote.

[Carreau]

The SIAM paper is also a good resource. As an FYI, there's a new Google Docs theme for Jupyter that is similar to the one for Keynote.

I don't think we should bother really thinking about theming. It will use the SciPy proceeding theme in the end. As we _likely_ do not have ma lot of math, I would suggest working on a RT shared doc and converting to RST later down the line.

[willingc]

I agree that the theme isn't needed for the written document. I mentioned it as an FYI for folks that were speaking at SciPy if they would like to use it ;-)

[choldgraf]

Hey all - I've put together an outline and some suggested topics for the Binder@SciPy draft. I've updated the TLC with a link, and am also pasting it here:

https://docs.google.com/document/d/13VQaXM_2ZRBVkM9KskzpAzSsEuKnfAZkLSuQfVtDySE/edit?usp=sharing

It's a Google doc to make collaborating easier, and we can convert to rST just before submitting.

We have about 3 weeks to get a first draft ready.

It'd be great if we can work together this one! This will be the most "official" academic/research artifact about Binder, so we should make sure it's good! Just a note that the paper itself will follow the jupyterhub authorship guidelines.

[choldgraf]

Another update - @mpacer and I updated the outline, and have a new outline draft here:

https://docs.google.com/document/d/13VQaXM_2ZRBVkM9KskzpAzSsEuKnfAZkLSuQfVtDySE/edit?ts=5af0ec10#

It's still evolving, and it'd be great if folks could give their thoughts/edits/comments/etc. The hope is to finalize it tomorrow or Friday, and then get a draft we can start working on ASAP.

[betatim]

Not sure which direction the paper is currently aiming. IMHO we should not cover the technical details in too much detail and instead focus on why binderhub is useful to people (say researchers and data scientists at a company). Why is it the solution to the problems our users have.

For example I would mention k8s in passing but I don't see a reason to spend a lot of time justifying why k8s instead of some other orchestration tool. While this is an important decision, as a user of a Binderhub I care that Binderhub "just works" and is easy to use. If we were writing this with a sysadmin audience in mind justifying k8s would be more important.

[choldgraf]

@mpacer and I grappled a bit with this as well. I feel like scipy is aimed both at scientists using these tools, and also at a more technical audience. Particularly since we'd love to see institutions get interested in deploying their own binderhubs etc, I feel like there's value in hitting both.

I was thinking we could cover the technical details inasmuch as they feed into the higher-level design decisions and principles of the project. As you mention, the specific pieces of technology are less important than why we chose them.

@ others, I'm hoping to start working on a draft of this tomorrow, so input on the outline would be appreciated before then. We need to have a first draft of the paper ready for reviewers by the end of next weekend. cc @minrk since you'll be @ scipy!

[choldgraf]

Hey all - I put together a first draft of the paper from our outline. Please add your comments/thoughts/edits/concerns/etc to the Google doc! Once we've got a relatively stable draft, I'll convert to rST so we can submit via the scipy build process.

https://docs.google.com/document/d/13VQaXM_2ZRBVkM9KskzpAzSsEuKnfAZkLSuQfVtDySE/edit#

A few quick thoughts:

• We have ~9 days before the review process starts, so we need a draft in "good enough" shape by then
• The draft is probably running long (a bit hard to tell on our page limit until we convert it to rST and try the build process)
• The draft is _loosely_ written in rST - please keep edits along these lines as well to facilitate our eventual conversion :-)

Here are some specific things that need work

• In general, I've marked to-do items as "TODO"
• There are a few sections with content placeholders, help fill these in!
• Add references to relevant locations
• Add figures that highlight the stuff we're talking about
• There are a few things that didn't easily port over from the outline, so please compare the draft to the outline and make minor or major changes!
• In general, any input is appreciated. I want to make sure that we're framing the project, its goals, and its technical details in a way that the team is happy with!

cc @minrk @willingc @mpacer @betatim @yuvipanda @jzf2101 @Carreau

[jzf2101]

@choldgraf I haven't forgotten to review

[choldgraf]

@jzf2101 would be great to hear your thoughts! :-)

[choldgraf]

Thanks so much for the edits @willingc , @minrk , and @betatim - for those that have taken a pass at the paper, I also want to make sure that folks think it's heading in the right direction in general. What do you all think about the overall tone / structure / topics of the paper? Is it accomplishing what you think it should accomplish? And feel free to suggest ways in which we should change or extend it!

[betatim]

I think we are going in the right direction.

Thinking about how to shorten things: should we reduce the technical detail (eg API description) and instead put pointers like "This REST API is documented here"?

[choldgraf]

hey all - FYI I'm converting the paper to rST now so that we can figure out how much we need to cut.

[willingc]

@choldgraf I think it's headed in the right direction. If anything, sometimes we get into the deep technical details without providing the reader enough context. I'll re-revieew after we have a rst file.

[choldgraf]

Hey all - I've got the paper converted to rST! Good news: we still have ~1.5 pages to work with! Here are some relevant links (I've updated the top-level comment as well):

• repository with rST version of paper (note that we're on the 2018-binder branch)
• latest PDF of the paper

I've added you all to my clone of the scipy-proceedings repository, please make subsequent edits/comments in the form of pull-requests!

[choldgraf]

cc @freeman-lab @andrewosh @rgbkrk @fperez since you're on here as well, as fellow members of the Binder team :-)

We would love your feedback on the latest draft of the scipy paper! (see top level comment for more info)

[choldgraf]

hey all - I added a few more pieces in there about the REST API as well as sustainability models and cost for mybinder.org. I also added a short list of "things you could help out with" at in the top-level comment: https://github.com/jupyterhub/binderhub/issues/529#issue-315597041

[betatim]

Good news: we still have ~1.5 pages to work with!

If we can write a paper that is 2 pages below the limit that would be awesome! People might actually read it :) -> I would try and resist adding stuff purely because we have space to add things. IMO a well written short paper is much more preferable than a medium-ly well written long paper (and a long and well written paper is very hard work to produce).

[choldgraf]

@betatim I totally agree :-) the reason I framed it as "good news" was because I remembered a few spots in the paper where we weren't sure if we could include something because we were over the limit.

That said, IMO we should always welcome edits that reduce the word-count ;-)

[betatim]

We should especially welcome edits that reduce word count, including edits to remove words like especially ;)

[choldgraf]

Hey all - we need a reviewer-ready version of the paper by Wednesday, May 23rd. For those of you who have been considering taking a pass at the paper, it would be quite helpful if you could do this by then.

[rgbkrk]

Does the PDF link above resolve to the latest copy of the paper?

Update: I suppose I could just read the rst and make a PR as you suggested. 😄

[choldgraf]

I think that the scipy proceedings build server actually generates the latest PDF off of this branch, so the place to look is:

http://procbuild.scipy.org/download/3

@mpacer do you know if that URL will be updated with new builds as new commits come in, or will it get bumped to a different number under /download/ (e.g. http://procbuild.scipy.org/download/28)?

[willingc]

Probably makes sense to add JupyterHub to the index items.

[choldgraf]

@willingc I'm not sure exactly what you mean. What are the index items?

[willingc]

@choldgraf If you look at the PDF, they are right below the abstract. Perhaps they are auto-generated?

[jzf2101]

FWIW it seems as if we should mention a bit of previous work eg the work of Victoria Stodden and CodaLab- can I plug that in?

https://halshs.archives-ouvertes.fr/halshs-00739233/document
https://arxiv.org/pdf/1704.02319.pdf

[mpacer]

@willingc Do you mean adding JupyterHub as an author to the paper? I think that (technically) is a violation of the Jupyter publishing guidelines: https://github.com/jupyter/governance/blob/master/papers.md

But I fear I may be misunderstanding your concern?

[choldgraf]

@willingc ahh I see what you mean, good call

[choldgraf]

@mpacer I believe she means adding it to the list of "keywords" which in the PDF get called "Index Terms"

[mpacer]

OH! when i put my co-chair hat on, I think I'll be asking us to dramatically reduce the number of terms there, but as an author I'm all for adding another :)

[choldgraf]

also @mpacer do you have any suggestions for how to get the code blocks to fit within the column? (other than just reducing the number of characters per line?)

and re: terms, I just threw in as many as I could think of, I don't have a problem removing a bunch

[choldgraf]

hey all, I am gonna step away from the computer for a little bit, will check back in periodically tonight to merge things, and will take a last pass before going to be in about 90 minutes or so...just FYI

[mpacer]

@choldgraf i'm of two minds

cochair hat: reducing the number of characters per line is all you've got right now, but it does make the code more readable

publisher hat: We should probably reduce the font size of the monospace font in general as it seems to sort of overwhelm the page as it is.

[mpacer]

@choldgraf this is looking pretty complete already — I'm not too concerned if we don't get too many more changes in

[choldgraf]

re: the code, would it be reasonable to choose a font size that ensures code that matches PEP8 line lengths would fit within a column? Seems like a reasonable criteria if a semi-arbitrary decision about size needs to be made (unless that would make it too small)

[betatim]

Can we make an option so that the code sections span both columns? Might be generally useful if we could get that into the style sheet.

[choldgraf]

Hey all - there's no official "submit" step since submission is just opening a PR (which has been open for a while), so I'll just take this moment to say thanks to everybody who helped make changes / suggestions / etc for the paper! (and of course who have helped out with the project more generally as well)

[mpacer]

i think that would make it too small unfortunately.

[choldgraf]

Hi team - we are making lots of good progress on the paper in https://github.com/scipy-conference/scipy_proceedings/pull/386

As we get closer to the date of scipy, we should start working on the presentation for scipy! Perhaps we can create a google slides and start working from there? Let me know your thoughts!

Who all is going to scipy this year? Thus far I know of me, @minrk and @mpacer .

[jzf2101]

I am not attending. However, I have slides I can share.

[choldgraf]

Hey all - a friendly ping to see if someone would like to take a stab at an outline for the slides - it's the next item on our list!

If you'd like, you can see this folder for several previous presentations that have been given on the JupyterHub/Binder ecosystem.

https://drive.google.com/drive/folders/1l-j6OjhnXOETe6HqS0iunIDWQX-OT2WN?usp=sharing

I've been putting all JupyterHub-related talks in here so that others can fork/modify/update as they wish. Please feel free to do so!

and in particular here's the latest JupyterHub/Binder/repo2docker talk I've given:

https://drive.google.com/open?id=1-adaPdEmtbg7FAHOVvznSPCmoez-jqvXlMYPvKTLi4o

I believe that @jzf2101 also has slides too from a previous conference talk that could get us started.

I'm happy to change up the design from the previous Binder/JupyterHub talks and demos, though I ask that we stick with Google Slides so that everybody can contribute / share more easily.

[betatim]

There are also markdown versions of Chris' slides here with some small edits from me.

My favourite part is the slide with the embedded life grafana plot and the challenge to everyone to launch a binder now ;) People always look a bit sceptical. Might need to change the link to a special repo or so.

[minrk]

Thanks for the links! I think we can start from there. Who wants to be up front doing the talking? Chris, M, and I are all listed as speakers, but we don't need to all stand up front if we don't want to hand off too many times. I'm okay either way!

[willingc]

@choldgraf @minrk @betatim @jzf2101 @yuvipanda, A few thoughts for the slide decks:

• Before Farica graduated, I had her create Jupyter Theme slides for Google Slides. Here's the link: https://docs.google.com/presentation/d/1XDiHJryEexP9ZoLJgo_RPl7iLQtn7GWPeEWZQjdAsvI/edit?usp=sharing

• Over time, it may be preferable to transition to a light color background instead of black. If the room is large (esp. larger conference ballrooms) or the projector old, it can be difficult for the audience to read text on a black background.

• Thanks Chris for moving the talks into one directory :-)

[choldgraf]

I am happy to speak if that's what's best for the team, also happy to share the stage with folks!

re: the design of the google slides, I'm +1 on standardizing our google slides on a "jupyter theme". The current design of our Z2JH slides is mostly a carryover from semi-arbitrary themes we picked up like a year ago :-)

re: white/black colors, I think that's a good point @willingc

do we have a specific place where slides templates etc go? It'd be helpful if there were one place where presentation materials existed so that we don't reinvent the wheel as much!

[betatim]

+1 on dark writing on light background slides.

Google slides is good.

We should make an effort to keep images/drawings outside it somewhere in their original form. At least I can't figure out how to get the original image out of a google slide deck again which means if we want to reuse drawings/images in a document we end up with crappy screenshots :(

[choldgraf]

Hey all - friendly ping that we are giving this presentation next week. Do we have any start on the slides? I'll be AFK-ish until Thursday (when I'm back from Kansas City) and can help out with slides in earnest starting then

[jzf2101]

@choldgraf I can help after I finish tying up the r2d stuff

[minrk]

I've been assembling the slides from the Jupyter theme in the folder, and put the base Jupyter template in there as well. The outline's derived from the paper.

[choldgraf]

nice @minrk ! I'm back from getting sort-of married and can work on this a bit now. I took a look and fleshed out the outline a little bit. Are folks OK with me putting together a brief draft of the slides?

[willingc]

@minrk The slides look great with the Jupyter theme. Thanks for doing that. One suggestion for the audience - Change slide 11 to have the title on the left side; remove comment re: complete example; increase the size of the code to fill the space.

[choldgraf]

I added some more content to the slides and fleshed things out a bit - still a ways to go but we are getting there!!! Feel free to edit/add/remove/add party parrots/etc if anybody has some cycles. I need to 💤 now but will jump back in w/ folks tomorrow!

[minrk]

Yes, everyone please feel free to keep working on the draft when they have time! I'm off today, but will be back to it a bit over the weekend.

[choldgraf]

Hey all - I'm gonna take another pass at the slides this morning to try and get them in a state that others can review etc! I'll collect a list of actionable items here, then push them to the top-level comment when I'm done so that others have opportunities to jump in if they have the time!

Things to do for the Binder @ SciPy presentation

• Find a Binder repository that highlights reproducible publishing (slide). (could be the LIGO project, just wondering if something new has come out worth highlighting)
• Last section on running / sustaining an open public service (mybinder.org) (slide)
• Final slides on what's next for Binder (slide)
• General run-through, comments, etc!

[choldgraf]

Hey all - I added the list above to the top-level comment. It'd be great if others could pitch in and add content/make improvements/etc! We are making good progress!

We are presenting Thursday at 4:30pm (link)

@minrk and @mpacer and I should also meet sometime soon to figure out logistics around the presentation itself. I'm arriving in Austin tomorrow! Shall we just chat in person about this, or figure it out on Gitter / email?

[willingc]

@choldgraf @minrk @mpacer I've left some comments on the content/slides. One overarching comment would be to see if you can shorten some of the bullets. A few slides have a lot of content.

[choldgraf]

This paper is now published!!!! here's a link and here's the DOI: 10.25080/Majora-4af1f417-011

I'm closing this issue since I think there's nothing actionable anymore. Congratulations everybody :-)