search

jupyterhub / mybinder.org-user-guide

Turn a Git repo into a collection of interactive notebooks. This is Binder's user documentation repository.
https://mybinder.readthedocs.io
BSD 3-Clause "New" or "Revised" License
153 stars 103 forks source link

Binder 2.0 announcement blog posts #22

Closed choldgraf closed 6 years ago

choldgraf commented 6 years ago

A place to discuss the Binder 2.0 blog post, currently planned for publishing on the eLife blog. eLife has slots open for a blog post on November 9th, as well as a few dates at the end of November.

Links

Binder blog post hackmd in case we want to iterate there. As the Jupyter blog post was in docs, I figure this will be an easier platform for people to leave comments, edits, etc. We can transfer to hackmd if that's what people prefer.

Other notes

thoughts from naomi on the eLife topic:

From my perspective, it would be great to tell the story of how the team picked up Binder, why it needed further work, what you have done, and how readers can act on this info - e.g. try it out, contribute. The aim is to spread the word about Binder to life scientists, so this blogpost could act as a news piece, with links to your own blogs for further detail. However, technical details are also very welcome.

willingc commented 6 years ago

Thanks @choldgraf. FYI @minrk @yuvipanda @mpacer @jzf2101 @Carreau @fperez @ellisonbg

Prior article for reference - 18 months ago

Folks currently interested in writing the draft: @choldgraf, @mpacer, @jzf2101 {Others, please feel free to add yourselves here too}

choldgraf commented 6 years ago

perhaps this blog post could be a way to lay out one snapshot of the ideas around jhub vs. binderhub etc...an opportunity to disambiguate the two

mpacer commented 6 years ago

Given what Naomi is saying, it sounds like we should plan an accompanying piece on the Jupyter blog?

I'm honestly a little skeptical that a piece that focuses on the technical changes that we've implemented would be a good way to interest life scientists into using Binder. It would definitely draw some attention to people who want to contribute to Binder.

However, I'd guess that there are many more people who are going to want to use Binder than who want to contribute to Binder. My intuition is that the Jupyter blog will be drawing a more technically focused audience and the eLife blog will draw a more research focused audience.

With that in mind, my suggestion is to use the eLife blogpost to describe how to use Binder and the Jupyter blogpost to describe the technical details of what is happening in Binder and how to set up BinderHub and Zero2JupyterHub.

For the elife article I'd think the following would be good elements to include:

choldgraf commented 6 years ago

Totally agree - I forgot to add a link in the top comment (just added it) to a google doc w/ a blog post draft that we wrote up a few months ago. The idea was that this one would go onto the jupyter blog and be more tech / changelogy, while something like elife would be more like a vision for where binder (and maybe jupyterhub) fit into scientific / publishing workflows.

I'm not sure the right balance between those two things, and how they should be split across the two posts, so feedback on that would be great. Also worth noting that the eLife blog post (well, both posts probably) should be relatively short (maybe 600-800 words).

Carreau commented 6 years ago

One important thing that can cover several blog post (but that we probably want to clarify for us to have consensus and guideline) are the semantic distinction of various terms used. There was a lot of confusion a binder/mybinder/jupyterhub/jupyter/notebook. Having a clear delimitation of the ephemeral nature of binder (which I think we mostly agree upon) might be a good thing.

I'm +1 on binder impact and usage on eLife, a a more technical series on the Jupyter blog.

willingc commented 6 years ago

Link to nomenclature that we were tossing around in August.

My intuition is that the Jupyter blog will be drawing a more technically focused audience and the eLife blog will draw a more research focused audience.

With that in mind, my suggestion is to use the eLife blogpost to describe how to use Binder and the Jupyter blogpost to describe the technical details of what is happening in Binder and how to set up BinderHub and Zero2JupyterHub.

Seems like a reasonable approach to me.

choldgraf commented 6 years ago

Hey all - I added a draft of the eLife blog post, and added some small updates to the Jupyter blog post. I made the new post in google docs so it's in the same format as the Jupyter post. I think that'll make it easier for people to comment, make suggestions, etc. However if people want I can transfer these to hackmd.

I've edited the top-level comment with new links, and pasted them here as well:

Would love to have some rounds of feedback, edits, etc!

As a side note, Naomi said they have a blog post slot open on November 9th. She mentioned it'd be nice to know by the end of the week if we'd like to post then. Anyone have thoughts on that? I think we should soft-launch the mybinder.org deployment before then to make sure all is well.

choldgraf commented 6 years ago

pinging @mpacer @jzf2101 @willingc @minrk @Carreau @fperez and @yuvipanda in case y'all aren't following this thread :-) feel free to contribute as much or as little time as you like!

choldgraf commented 6 years ago

ooh and maybe @betatim and @ctb as well!

choldgraf commented 6 years ago

ok made a few updates and reorganization per people's comments (on the elife post). The beginning is now more focused on the motivating reason for Binder and use-case demonstration. Also structured things into headings/subheadings/etc.

ctb commented 6 years ago

Just read 'em - I think these are nicely complementary to each other, as well as to the binder workshop blog post (here). Nice work!

ellisonbg commented 6 years ago

OK I took an editing pass at both of these - overall looking good! I left comment, made edits, etc. Awesome!

On Tue, Oct 31, 2017 at 5:48 PM, C. Titus Brown notifications@github.com wrote:

Just read 'em - I think these are nicely complementary to each other, as well as to the binder workshop blog post (here http://ivory.idyll.org/blog/2017-binder-workshop.html). Nice work!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/binder/issues/22#issuecomment-340947672, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0MhslzxNa5uH9xfv0G2rxLX52-HUks5sx7_NgaJpZM4P50pr .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

betatim commented 6 years ago

How do we keep this rolling? We missed November 9th so we have two-ish weeks till the "end of November" slots on eLife (to create a deadline for ourselves.)

I will go through the eLife post and accept changes that I think are uncontroversial now. I think to wrap up the (few) loose ends left we should maybe add a task list to the first comment so everyone can see what is still left to do.

choldgraf commented 6 years ago

Yep I agree, I'm going to send an email between Naomi and this group to plan the announcement. Nov 9 felt like a rush since some kinks are still getting worked out. Feel free to make any suggestions or edits! I'm planning to take another pass this weekend.

choldgraf commented 6 years ago

Hey folks - I took another pass at making edits, addressing comments, etc. It'd be great if somebody could take another pass through to make sure that's been done to everyone's satisfaction :-)

Right now there are a few points where we mention links to repositories to demo functionality etc, most of those links are just placeholders right now. If someone has 30 minutes, it'd be helpful if someone could hunt down some good repos to show off.

betatim commented 6 years ago

There are a few comments left about finding links/examples. Those still need finding/deciding.

The other comments are a mixture of commentary/general remarks and edit suggestions. To try and close them could you go through the ones you opened and either close them or make a concrete edit to the document (in suggestion mode) that would satisfy you? At this stage I'd suggest that all comments which don't come with a concrete edit are closed and we keep them in the back of our mind for the future.

My main complaint now would be that the post is pretty long. So removing stuff is what I would focus on. Thinking more "trailer" instead of "feature length movie". Given that most people's prior will be "never heard of binder" showing that we thought about starting from DOIs instead of GitHub repos is a detail that is probably irrelevant (to pick on something that is dear to my heart).

npscience commented 6 years ago

I've taken a pass at some editing on the doc too (for the eLife post).

I think this post is great, really useful examples, and I like that you have stated the values of the project too.

Honestly, I think Tim's cycling example is the best one to include to demonstrate the power of Binder — the content is understandable by a lot more people than a specific biological one would be.

There was a comment about mentioning Binder-as-a-service. A small section (1-2 paragraphs) about 'Sustaining Binder' would be really awesome to see, even if it's only a brief overview of your current plans. People are always interested to understand how to sustain OS projects, so you'd be leading by example in this ecosystem.

In terms of finalising, there are some URLs to add in. I reckon I could help to slim it down a bit more too, plus we need an image to use on our listings page. I've added the requirements for that in the post. Maybe you wish to use the Binder logo?

choldgraf commented 6 years ago

Thanks for the comments @npscience ! I've addressed most of the comments/ideas/suggestions, as well as added in images from Tim's repo. A few thoughts to discuss below:

all: we have about one week to publication, so if you have a minute please make any final comments / edits / etc.

jzf2101 commented 6 years ago

@choldgraf see https://github.com/jupyter/governance/pull/27 for general authorship guidelines. For the medium, we have an individual submit.

choldgraf commented 6 years ago

makes sense re: academic papers...I guess this is more of a blog post (though I think it will have a DOI, right @npscience?). I am happy with whatever the community norms are here.

jzf2101 commented 6 years ago

@ellisonbg how do you think we should square it? our norm on medium is single authorship?

@choldgraf we reference non first authors in the blogposts eg LIGO

choldgraf commented 6 years ago

IMO if it's going to be a single author, then it should be "Project Jupyter" or something like this.

ellisonbg commented 6 years ago

Medium only really allows one official author, so options:

In terms of who is listed by name, I would say, the entire JupyterHub/Binder team and then anyone who worked enough on the text to be included.

On Mon, Nov 20, 2017 at 2:30 PM, Chris Holdgraf notifications@github.com wrote:

IMO if it's going to be a single author, then it should be "Project Jupyter" or something like this.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/binder/issues/22#issuecomment-345838145, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0N6wRUJkffKqUbWvULmgTmTlCr-qks5s4e9xgaJpZM4P50pr .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

jzf2101 commented 6 years ago

@choldgraf I also just wanted to highlight @jvns 's blog post and the build of her pandas cookbook . Perhaps we could reference it ?

willingc commented 6 years ago

Excellent suggestion!

npscience commented 6 years ago

Thanks for all your continuing edits. I'm a bit pushed right now but I am going to try to jump back on on Friday to consolidate, then we can work out what's left to finalise.

FWIW, it would be good to have it finalised your side by end of Monday (27th), so I can do necessary finalising on our end ready for our deadline (30th). Does that sounds achievable for everyone?

Thanks!

npscience commented 6 years ago

@choldgraf, we don't actually DOI our blogposts (there's no need), but I have no objection to cross-posting elsewhere if you would require a DOI.

Re bio software packages, I wish I'd had more time to look into this. I'll try to on Friday, but totally fine to use a non-bio example if you need.

Re governance, I'll take a look at the text on Friday. Absolutely understand any need for sensitivity.

ellisonbg commented 6 years ago

Hi all,

I have added a full list of potential authors to the eLife draft. I have taken the liberty to add everyone here who has commented on the draft or GitHub issue. If you don't want to be listed as an author, please let us know or remove your name. Also if someone can double check to make sure I haven't missed anyone and that I properly did the alphabetical ordering, that would be great.

I also made some other edits/comments.

Cheers,

Brian

On Tue, Nov 21, 2017 at 1:13 PM, Naomi Penfold notifications@github.com wrote:

@choldgraf https://github.com/choldgraf, we don't actually DOI our blogposts (there's no need), but I have no objection to cross-posting elsewhere if you would require a DOI.

Re bio software packages, I wish I'd had more time to look into this. I'll try to on Friday, but totally fine to use a non-bio example if you need.

Re governance, I'll take a look at the text on Friday. Absolutely understand any need for sensitivity.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/binder/issues/22#issuecomment-346147325, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0C9OTcsDv1Pv4kbwGmMtEa0BZCiwks5s4y7_gaJpZM4P50pr .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

npscience commented 6 years ago

I've taken another sweep and made some suggestions. I'm happy with how this reads now, and would like to involve some others at eLife for final proofing steps. Before I do so, it would be good to consolidate or finalise the current suggested edits on the doc. @choldgraf might you be able to coordinate this from your end, please?

I'll be ready to circulate internally on Monday/Tuesday, so we can finalise for sure on Wednesday and post on Thursday.

Thanks all!

choldgraf commented 6 years ago

Yep, my plan is to take a final pass tomorrow after the holiday! Thanks so much!

On Thu, Nov 23, 2017, 12:00 PM Naomi Penfold notifications@github.com wrote:

I've taken another sweep and made some suggestions. I'm happy with how this reads now, and would like to involve some others at eLife for final proofing steps. Before I do so, it would be good to consolidate or finalise the current suggested edits on the doc. @choldgraf https://github.com/choldgraf might you be able to coordinate this from your end, please?

I'll be ready to circulate internally on Monday/Tuesday, so we can finalise for sure on Wednesday and post on Thursday.

Thanks all!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/binder/issues/22#issuecomment-346676109, or mute the thread https://github.com/notifications/unsubscribe-auth/ABwSHVXV4HRBLSwo4ObKle5eCMMKmLTgks5s5bK7gaJpZM4P50pr .

choldgraf commented 6 years ago

OK, I just took a look through the final comments and made edits per the suggestions that were there. I didn't "resolve" comments so if you think it's been addressed well-enough feel free to do so yourself!

There are some small-ish items remaining, but I don't think that should be blocking on @npscience 's team taking a pass themselves. That said, these are the main things remaining to do:

  1. I believe @freeman-lab was hoping to take a pass...that should happen sooner than later if you have time, Jeremy :-) I think @npscience is hoping to have a more-or-less finalized draft by Monday morning (which is Sunday night for us).
  2. There are still edits to make to the Jupyter teach blog post, and I'll take a pass at this once we are OK with this draft. Thanks for your comments on that post thus far!
  3. We should agree on a GitHub tag that we'll use for binder. I know there was discussion of this somewhere but I can't find this issue :-/

Anything else?

npscience commented 6 years ago

Hello

@choldgraf Just to let you know that we have run this by the team here, and are happy and ready to post on Thursday.

Unfortunately, we are unlikely to be able to include the 'launch binder' button linked to the URL to launch Tim's notebook due to restricted features on the Drupal site that runs our blogs. The developers aren't able to prioritise adding this simple feature, and the Drupal site does not support an html hack to get this in. Would it be a disaster to include the URL from the text, instead of the 'launch binder' button? Sorry about this.

One final thing to tie up are the mutual URLs to each other's posts. I can find out our one on Thursday morning (UK) before publishing; is it possible to find out the Jupyter blog URL before posting?

What time do we want to aim for? 4pm UK is morning west coast.

I'll drop an email round to discuss dissemination plans, so we're on the same page there.

ellisonbg commented 6 years ago

On Tue, Nov 28, 2017 at 9:34 AM, Naomi Penfold notifications@github.com wrote:

Hello

@choldgraf https://github.com/choldgraf Just to let you know that we have run this by the team here, and are happy and ready to post on Thursday.

Unfortunately, we are unlikely to be able to include the 'launch binder' button linked to the URL to launch Tim's notebook due to restricted features on the Drupal site that runs our blogs. The developers aren't able to prioritise adding this simple feature, and the Drupal site does not support an html hack to get this in. Would it be a disaster to include the URL from the text, instead of the 'launch binder' button? Sorry about this.

Maybe let's put this on the Jupyter blog post and include just a text link in the drupal post.

One final thing to tie up are the mutual URLs to each other's posts. I can find out our one on Thursday morning (UK) before publishing; is it possible to find out the Jupyter blog URL before posting?

No, not that I know of. We will have to both post the blogs, then grab the URLs and then update both to point to the other.

What time do we want to aim for? 4pm UK is morning west coast.

I'll drop an email round to discuss dissemination plans, so we're on the same page there.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/binder/issues/22#issuecomment-347581987, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0PaSQvZZZn8ymbvk467Lr8EtaEoiks5s7DYagaJpZM4P50pr .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

choldgraf commented 6 years ago

ok all, the plan is to post on Thursday! Some thoughts below.

@Carreau can you step me through starting a new post on Medium? I can only seem to create one that's attached to my account, not the project jupyter blog...

re: timing, sounds good to me. I think we're ready to go. For other folks on this issue, please speak now if you have thoughts/comments!

re: links, we should be able to get the link on medium before we publish. Will get that to you once @Carreau helps get me set up with the blog.

re: launch binder button, I think it's OK if it's not possible (sounds like we don't have much of a choice). What if we just used regular old text and enlarged/centered it? I put this in the draft to see how this looks. Would that work?

re: tags, why don't we use binder as a tag? A number of repositories have already started using it independently of us, so it seems that this tag is intuitive for users in our (small) sample. There are a couple repos not related to mybinder.org with a binder tag, but they are relatively few. (there seems to be a tool in the Android ecosystem called binder). thoughts?

pinging @minrk @yuvipanda @mpacer @jzf2101 @Carreau @fperez @ellisonbg @willingc @betatim @ctb @freeman-lab in case they aren't following the thread and would like to give thoughts. Please ping others if I've left anybody out.

npscience commented 6 years ago

re: launch binder button, I think it's OK if it's not possible (sounds like we don't have much of a choice). What if we just used regular old text and enlarged/centered it? I put this in the draft to see how this looks. Would that work?

@choldgraf commented in doc - we can do this a little nicer, just not with your image at this point. (And thank you for spurring a new feature to add to our site...)

ellisonbg commented 6 years ago

On Tue, Nov 28, 2017 at 10:16 AM, Chris Holdgraf notifications@github.com wrote:

ok all, the plan is to post on Thursday! Some thoughts below.

@Carreau https://github.com/carreau can you step me through starting a new post on Medium? I can only seem to create one that's attached to my account, not the project jupyter blog...

As for the Medium post, we could do it two ways:

1) You can author it as you, and then "submit" it to the Jupyter Blog "publication" for addition - we would get an email and then do a final review 2) One of us can log in as the ProjectJupyter account and directly publish it

I am fine either way - in both cases we will have a larger author list that we have to add by hand.

1) might be easier as you can just get started right away...

re: timing, sounds good to me. I think we're ready to go. *For other folks

on this issue, please speak now if you have thoughts/comments!*

re: links, we should be able to get the link on medium before we publish. Will get that to you once @Carreau https://github.com/carreau helps get me set up with the blog.

I can help on this too.

re: launch binder button, I think it's OK if it's not possible (sounds like we don't have much of a choice). What if we just used regular old text and enlarged/centered it? I put this in the draft to see how this looks. Would that work?

re: tags, why don't we use binder as a tag? A number of repositories have already started using it independently of us, so it seems that this tag is intuitive for users in our (small) sample. There are a couple repos not related to mybinder.org with a binder tag, but they are relatively few. (there seems to be a tool in the Android ecosystem called binder). thoughts?

you mean "topic"....I am fine with that, but the other folks using it may not be ;-)

pinging @minrk https://github.com/minrk @yuvipanda https://github.com/yuvipanda @mpacer https://github.com/mpacer @jzf2101 https://github.com/jzf2101 @Carreau https://github.com/carreau @fperez https://github.com/fperez @ellisonbg https://github.com/ellisonbg @willingc https://github.com/willingc @betatim https://github.com/betatim @ctb https://github.com/ctb @freeman-lab https://github.com/freeman-lab in case they aren't following the thread and would like to give thoughts. Please ping others if I've left anybody out.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/jupyterhub/binder/issues/22#issuecomment-347595801, or mute the thread https://github.com/notifications/unsubscribe-auth/AABr0A5M7nX8gwwa9-g-CdrOy81OPzXMks5s7D_ugaJpZM4P50pr .

-- Brian E. Granger Associate Professor of Physics and Data Science Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

willingc commented 6 years ago

@choldgraf I'm assuming you are referring to tags for the github SEO on other folks' repos. I would recommend binder and binder-ready.

choldgraf commented 6 years ago

@willingc yep! sounds good. do we just use these two interchangeably?

@ellisonbg my bad! topic not tag! Forgot we had clarified that in the doc

choldgraf commented 6 years ago

also sounds good re: blog post draft, at the end of today I'll upload the tech post to medium and we can start iterating there

willingc commented 6 years ago

I would recommend using both interchangeably. Here's the current usage of binder as a topic. A bit concerned that binder is generic enough that others will use, which is fine; binder-ready would be more specific to the binder service.

ellisonbg commented 6 years ago

I am fine with either binder or binder-ready but I would strongly recommend picking one canonical (rather than both) as you want to be able to use it in various place without any ambiguity about what topic users should use to get their repo to show up, and what topic "consumer" users would visit to see them all. Having both will only dilute the impact and confuse users.

Carreau commented 6 years ago

@Carreau can you step me through starting a new post on Medium? I can only seem to create one that's attached to my account, not the project jupyter blog...

Sure, ghost draft

re: links, we should be able to get the link on medium before we publish. Will get that to you once

Yes, you'l get when you edit a url like https://medium.com/p/80e19f95e477/edit the hash is important, the final url will be :https://medium/title-of-the-post-<hash> I believe, the title-of-the-post does-not-matter. For example Min's latest blog post (https://blog.jupyter.org/public-notebooks-and-security-3058c433c884) is accessible as https://blog.jupyter.org/everything-is-awesome-3058c433c884

1) You can author it as you, and then "submit" it to the Jupyter Blog "publication" for addition - we would get an email and then do a final review

I prefer this than doing it with ProjectJupyter for our users to be exposed to the member of the community.

npscience commented 6 years ago

Hi all. Is there any way of tracking traffic on mybinder.org and the readthedocs, to see if there's any boost after these posts tomorrow?

I will be tracking views on eLife Labs, and can note engagement on the GH repos (binderhub, examples) before and after. I tend to use a 7 and 30 day period.

Some tables are in the dissemination plan doc, ready for entries.

betatim commented 6 years ago

For mybinder.org there is a google analytics account, not sure who has credentials for that.

We also (thanks to @choldgraf) have a notebook (that runs on binder...) which can produce plots of what repos were built over the last N days.

choldgraf commented 6 years ago

heya - yep we do have google analytics. anyone that would like access let me know and I'll add you!

here are weekly mybinder.org hits for the last couple months:

image

I also spent some time yesterday and got google analytics set up on all of the other major documentation pages for the Binder project, so we should be able to see a nice bump if it exists.

@npscience in my experience one of the best ways to drive traffic with Binder is to find a cool repo that people want to interact with. E.g., the Data Science Handbook that Jake van der Plas put together was super popular.

@Carreau I'll run through that today will post to medium! Thanks for the gif!

willingc commented 6 years ago

@choldgraf please add me to the google analytics. Thanks for setting up the doc pages for it.

Carreau commented 6 years ago

@choldgraf please add me to the google analytics. Thanks for setting up the doc pages for it.

Me too please, I started to add Analytics to some of my own website and can try to do it for a couple of JupyterHub/Binder docs things as well.

I saw that @minrk created a draft Binder 2.0, will that be the one we publish ? Or was it just a test ?

Re-Analytics should we / could we have a google-analytics extension that also track how long user are spending on the notebooks themselves, or is grafana sufficient ?

minrk commented 6 years ago

@Carreau that's not a real draft, I was just looking into what URLs look like and how to share links. I'll delete that one now.

Carreau commented 6 years ago

Ok, I did it above, did you reach the same conclusions :

Yes, you'll get when you edit a url like https://medium.com/p/80e19f95e477/edit the hash is important, the final url will be: https://medium.com/title-of-the-post- I believe, the title-of-the-post does-not-matter

choldgraf commented 6 years ago

@willingc @minrk and @Carreau are currently all admins on the google analytics account!