Refactor and update the jupyter meta-docs

Meta
1

Right now we have some meta-docs at jupyter.readthedocs.io. They haven’t been updated super frequently, but they have a lot of great content. The theme the site uses also seems quite custom, and needs a little bit of work (e.g. the Jupyter logo seems to be the wrong size).

We’ve had some general conversation recently around improving the “meta” documentation in Jupyter. E.g. @parente has recently moved Docker Stacks to Discourse, and asked what we should do with the “contributing guidelines” page.

I propose that we do something like the following, and would love to hear what people think about it:

  • Change the theme of jupyter.readthedocs.io to something simpler like the jupyterlab readthedocs theme, or the jupyterhub alabaster theme.
  • Take a pass through the content in order to make sure the information there is up-to-date.
  • Move the “contributing guide” content here to this repository
  • Add some kind of “list of jupyter repositories” to this documentation, similar to http://docs.astropy.org/en/stable/stability.html
  • Edit the repository’s README to make clear they should ask questions in the Discourse, not the issues of that repo
  • In the future, treat this repository as the host of the “contributing docs”.
  • Potentially, rename this repository to something more descriptive, like “jupyter-contribute.readthedocs.io” or “team-compass.readthedocs.io”

What do folks think about this? (apologies if all of this has already been decided at some other point in time)

2

Baby-steps… :slight_smile:

BTW, the repo location for that site was not that easy to find – i.e. put “add a GH link” on the todo pile.

3

Bigger steps… :footprints:

4

nice, thanks for the patches @jhermann - I noticed that I don’t have merge rights on that repo, but I support the notion of updating that content :slight_smile: It looks like @willingc did a lot of the work on the site a while back, so perhaps she could give guidance on whether it makes sense to start updating the content there.

5

https://jupyter.readthedocs.io/en/latest/contributor/contrib_guide_blog.html#technical-overview talks about using Ghost for blogging – but it is Medium by now.

Also, the “guest blogger” intro text talks about making contact – should include something like “see below” for the impatient reader.

1 Like
6

It’s been a couple of years since I touched these docs. I would go ahead and make any PRs that make sense (re: Medium) and others. Perhaps @-mentioning @choldgraf @Zsailer @ruv7 and me for review.

It would be nice to get things up to date :smiley:

1 Like
7

@willingc I am happy to help review PRs there (though I don’t believe I have merge rights). I only discovered those docs after almost 2 years on the project - I really like the content that is in there and would love to help make update them and make them more discoverable!

1 Like
8

I just added you, @Zsailer and @Ruv7 as maintainers on the repo. Check your inboxes.

1 Like