# Improve documentation for new users not working on the master branch

**URL:** <https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509>\
**Category:** mybinder.org ops\
**Created:** [August 6, 2020, 1:38am UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509 "2020-08-06T01:38:24Z")\
**Posts on this page:** 13\
**Page:** 1

<div class="post-metadata">

**Author:** ![JessicaS11](https://avatars.discourse-cdn.com/v4/letter/j/d9b06d/32.png) [@JessicaS11](https://discourse.jupyter.org/u/JessicaS11)\
**Post date:** [August 6, 2020, 1:38am UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/1 "2020-08-06T01:38:24Z")

</div>

I spent way too much time today trying to construct a url to launch my repo on [mybinder.org](http://mybinder.org) from a branch other than master before someone pointed me to [nbgitpuller](https://jupyterhub.github.io/nbgitpuller/link) and I was able to generate a working link in a matter of minutes. I was surprised that I wasn’t able to find this site through the mybinder docs or even google. I’d like to add a sentence or two sharing this resource to the “Getting Started” page of the docs, but wanted to make sure there wasn’t a reason it was explicitly excluded from the docs currently.

---

<div class="post-metadata">

**Author:** ![sgibson91](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/sgibson91/32/487_2.png) [@sgibson91](https://discourse.jupyter.org/u/sgibson91)\
**Post date:** [August 6, 2020, 7:36am UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/2 "2020-08-06T07:36:20Z")

</div>

Hi! Can I ask why filling in the desired branch name in the box on the [mybinder.org](http://mybinder.org) form (highlighted below) didn’t work for you?

 ![web_form](https://canada1.discourse-cdn.com/flex031/uploads/jupyter/original/2X/6/6be3b86cce37abfe95f7ca792d28e4deff04f63d.png)

---

<div class="post-metadata">

**Author:** ![JessicaS11](https://avatars.discourse-cdn.com/v4/letter/j/d9b06d/32.png) [@JessicaS11](https://discourse.jupyter.org/u/JessicaS11)\
**Post date:** [August 6, 2020, 2:28pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/3 "2020-08-06T14:28:11Z")

</div>

Of course. The issue I had with using the [mybinder.org](http://mybinder.org) form was that it didn’t actually connect to my repository content, instead only displaying the binder configuration files:

 ![image](https://canada1.discourse-cdn.com/flex031/uploads/jupyter/original/2X/b/b4256057dde9f1506f714a0dc2343900c1c1f635.png)

The content does show up if I use the master branch, but I was trying to test the binder environment setup, which currently only exists on my working branch. I don’t want to point to one specific notebook (they’re all in subdirectories anyway), and adding the repo url as a “path to a notebook file” did not include them either. I’m also starting the instance into JupyterLab, which resulted in the same issue (no repo documents) when I added `?urlpath=lab` to the url, as indicated in the docs. So I’d taken to trying to manually generate a url from an older example I had in order launch a binder running JupyterLab and where the repo content showed up.

I’m setting things up for [this public repo](https://github.com/ICESAT-2HackWeek/2020_ICESat-2_Hackweek_Tutorials/tree/binder), which uses a docker image to provide environment settings.

---

<div class="post-metadata">

**Author:** ![sgibson91](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/sgibson91/32/487_2.png) [@sgibson91](https://discourse.jupyter.org/u/sgibson91)\
**Post date:** [August 6, 2020, 2:58pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/5 "2020-08-06T14:58:51Z")

</div>

Are you using two repos? One you’re testing with and the one you linked in your above post?

The [Dockerfile in the repo you linked](https://github.com/ICESAT-2HackWeek/2020_ICESat-2_Hackweek_Tutorials/blob/cdf56939a0b71f49587cdaa4e8a755ea568e653c/binder/Dockerfile) looks very bare to be used with [mybinder.org](http://mybinder.org). We recommend people start from the [minimal Dockerfile example](https://github.com/binder-examples/minimal-dockerfile) and built out to make sure everything will run properly.

But I can’t see where you’re testing with environment.yml, etc?

---

<div class="post-metadata">

**Author:** ![JessicaS11](https://avatars.discourse-cdn.com/v4/letter/j/d9b06d/32.png) [@JessicaS11](https://discourse.jupyter.org/u/JessicaS11)\
**Post date:** [August 6, 2020, 3:55pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/6 "2020-08-06T15:55:10Z")

</div>

No, it should all be one repo - the link points to the particular branch of the repo I am testing. The image shows what happens when I open that repo+branch combination from the mybinder-dot-org form (I’m a new user so I can only have two links in my post).

The Dockerfile points to an existing Docker image, I believe. @scottyhq - can you comment on that if I’m mistaken? After some digging, the `notebook` package is included within our docker setup (in the [pangeo-data docker base images](https://github.com/pangeo-data/pangeo-docker-images/blob/e9c65e887508df8d816e5653a37bd6b8bf80c7b0/base-notebook/conda-linux-64.lock), which [the repo that creates the referenced docker image](https://github.com/ICESAT-2HackWeek/jupyter-image-2020) uses).

---

<div class="post-metadata">

**Author:** ![sgibson91](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/sgibson91/32/487_2.png) [@sgibson91](https://discourse.jupyter.org/u/sgibson91)\
**Post date:** [August 6, 2020, 4:12pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/7 "2020-08-06T16:12:26Z")

</div>

Oh, then I have no idea where the environment.yaml, etc, in your screenshot are coming from 🤔 or indeed where your content files are going to either. Is the pangeo base image built to work with [mybinder.org](http://mybinder.org)?

Looking at the GitHub Actions the second repo uses to build the image, I will mention that we have a [repo2docker action](https://github.com/jupyterhub/repo2docker-action) that will automatically builds the images and create a [mybinder.org](http://mybinder.org) compatible Dockerfile, so perhaps that may help untangle this?

---

<div class="post-metadata">

**Author:** ![scottyhq](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/scottyhq/32/823_2.png) [@scottyhq](https://discourse.jupyter.org/u/scottyhq)\
**Post date:** [August 6, 2020, 4:23pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/8 "2020-08-06T16:23:57Z")

</div>

Hi @sgibson91 @JessicaS11! I think the key here is seperating the computational environment versus content (whether they are on separate branches, or separate repos) as described in this forum post [Tip: speed up Binder launches by pulling github content in a Binder link with nbgitpuller](https://discourse.jupyter.org/t/tip-speed-up-binder-launches-by-pulling-github-content-in-a-binder-link-with-nbgitpuller/922).

I suppose this is still considered ‘advanced’ usage. Plus it only works if your environment has nbgitpuller installed. In any case, I think the link generator on the nbgitpuller docs is really handy! Perhaps it’s worth linking to here [https://mybinder.readthedocs.io/en/latest/using.html](https://mybinder.readthedocs.io/en/latest/using.html) ?

---

<div class="post-metadata">

**Author:** ![sgibson91](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/sgibson91/32/487_2.png) [@sgibson91](https://discourse.jupyter.org/u/sgibson91)\
**Post date:** [August 6, 2020, 4:34pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/9 "2020-08-06T16:34:28Z")

</div>

Yes, we should definitely include a usage example in the context of separate env and content. I think I just got all confused over this particular example! 😅

---

<div class="post-metadata">

**Author:** ![choldgraf](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/choldgraf/32/1264_2.png) [@choldgraf](https://discourse.jupyter.org/u/choldgraf)\
**Post date:** [August 6, 2020, 4:40pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/10 "2020-08-06T16:40:03Z")

</div>

oh shit that’s a good idea! I had not thought to put the “environment” and the “computational content” on two different **branches**. That’s clever!

this is definitely an “advanced use case” which is why it isn’t documented well, but I think we should definitely improve that documentation. I’m +1 on finding ways to make this pattern more discoverable in ways that don’t _also_ complicate people figuring out how to build repositories the “default” way.

---

<div class="post-metadata">

**Author:** ![JessicaS11](https://avatars.discourse-cdn.com/v4/letter/j/d9b06d/32.png) [@JessicaS11](https://discourse.jupyter.org/u/JessicaS11)\
**Post date:** [August 6, 2020, 5:04pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/11 "2020-08-06T17:04:55Z")

</div>

> [@scottyhq](#):
>
> I think the key here is seperating the computational environment versus content (whether they are on separate branches, or separate repos) as described in this forum post [Tip: speed up Binder launches by pulling github content in a Binder link with nbgitpuller](https://discourse.jupyter.org/t/tip-speed-up-binder-launches-by-pulling-github-content-in-a-binder-link-with-nbgitpuller/922).

Thanks for clarifying that for us all! I’d be happy to put together a draft PR that adds a short note on this use case to the docs. Thoughts from those more familiar with the docs on where to put it? My instinctual place to look for the info yesterday was [Getting Started \> Common Usage Patterns](https://mybinder.readthedocs.io/en/latest/using.html), How-To Guides, or Tutorials. I didn’t think to look at any of the “speeding things up” links, though it seems like the discussion there ultimately tangentially addressed this issue and could be referenced.

---

<div class="post-metadata">

**Author:** ![choldgraf](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/choldgraf/32/1264_2.png) [@choldgraf](https://discourse.jupyter.org/u/choldgraf)\
**Post date:** [August 6, 2020, 5:23pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/12 "2020-08-06T17:23:09Z")

</div>

I’d be happy to review a PR like this, I think you are in the best position to know where to put it since you just went through the exercise of “looking for” the information!

My thinking is:

- document something in the location where others will instinctively look for it
- if there are many possible places, document it in one place and add lots of cross-refs to it

---

<div class="post-metadata">

**Author:** ![psychemedia](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/psychemedia/32/24_2.png) [@psychemedia](https://discourse.jupyter.org/u/psychemedia)\
**Post date:** [August 6, 2020, 8:00pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/13 "2020-08-06T20:00:51Z")

</div>

> [@choldgraf](#):
>
> oh shit that’s a good idea! I had not thought to put the “environment” and the “computational content” on two different **branches**. That’s clever!

Github conventionally uses the `gh-pages` branch as a “reserved” branch for constructing Github Pages docs related to a particular repo. I’ve idly wondered before about whether we could take a similar approach for defining a “Binder build” branch?

[via](https://blog.ouseful.info/2019/06/11/binder-base-boxes-several-ways/)

---

<div class="post-metadata">

**Author:** ![choldgraf](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/choldgraf/32/1264_2.png) [@choldgraf](https://discourse.jupyter.org/u/choldgraf)\
**Post date:** [August 6, 2020, 11:38pm UTC](https://discourse.jupyter.org/t/improve-documentation-for-new-users-not-working-on-the-master-branch/5509/14 "2020-08-06T23:38:34Z")

</div>

I think the it would add some complexity to the build process, but it’s an interesting idea. I guess the question is whether this pattern of separating environment and content is something we want to actively promote etc by making it easier on the tech side