Replace Documentation page with a link to Jupyter docs site #507
Conversation
|
The PR to the docs site is in jupyter/jupyter#590 |
There was a problem hiding this comment.
I think this is a reasonable change - it's good to have a single source of truth for the Jupyter documentation, and jupyter.github.io seems like a more reasonable place for this. A few questions:
Does it seem reasonable to make docs.jupyter.org point to jupyter.readthedocs.io and use that in general instead of jupyter.readthedocs.io? That feels more human-friendly to me.
@palewire one thing I'm a bit worried about is the duplication of other information here and in the docs. For example, the community page has some overlapping content with the "Get Involved" page here. What do you think?
|
I love the idea of docs.jupyter.org. Does it exist? Or would that be a patch to the RTD implementation, the DNS and such? |
|
I didn't realize there was community information over there in the Sphinx site. I agree it should be one place or the other. I'm agnostic about which, though my first hunch is it might be better off in this site so the design is consistent, it isn't technical docs, etc. But I think it could work either way. |
It was a DNS change - and should now work if you go to docs.jupyter.org !
The main thing we do is add minutes for community meetings in the community site, since that's a bit easier to update than a Jekyll site for many. I think the jupyter.org site is primarily a brochure + pointer site, so to me that means "high level information for people who are seeing it for the first time, and links to other places for more in-depth information". One other thought is that the docs.jupyter.org site should probably be more dynamic in general - we have more workflow patterns of commonly updating a Sphinx docs site than a Jekyll site. I'm not quite sure how that maps onto the content here vs. at docs.jupyter.org but does that give you any ideas for how the two could separate out? |
|
Alright, @choldgraf, I've updated the proposed change to https://docs.jupyter.org/. As far as the community page, I'm fine with the change if you think it'll be a win for the community. But maybe let's leave to another ticket down the road. |
|
Makes sense to not block this PR on that. However I do think we should make sure that the state of the jupyter docs is ready for a big infusion of traffic (I think jupyter.org has like one or two orders of magnitude of traffic). I opened up another PR there with some ideas. Any interest in a quick iteration or two in that PR, or in subsequent PRs, to prep before we merge this? I don't want to raise the bar too much but if we can get some low hanging fruit I think it'd be worth it. What do you think? |
|
To me, the bar is "Are you losing anything?" If the replacement is, at a minimum, as good as the current page, I think it's safe to merge. I haven't had a chance to look at your ticket over there yet. When I get a second I will and will let you know. |
|
I think this is wise - the main difference I can think of for the docs at jupyter.github.io is simply that there is a lot more information there in general, so I think the big downsides to think about are:
Other than that I agree any other changes would be "nice to have" |
|
I've gone ahead and added a redirect from the current URL to the docs site as well. |
|
I like this change and believe we should go forward with it soon. To help prepare for the change I created jupyter/jupyter#596, but it would be great if a few more eyes looked at the https://docs.jupyter.org |
|
there are merge conflict, once resolved I'm happy to stumble onto the merge button. |
|
Others in this thread (@palewire / @krassowski ) - anything else you think should be changed in jupyter.readthedocs.io before we merge this in? |
|
Nope. We should just make sure we also delete the cruft created by deprecating the page, which this patch tried to do. Would do it myself but I'm driving the 5 South to LA today. |
|
I'm back in LA and this is resynced with master. Ready to merge. |
|
🚀 |
As discussed in #505, the documentation page on this site doesn't have a clear focus, and it has become largely redundant of the project-wide Jupyter documentation on readthedocs. This patch would remove the page on this site and link there instead.
One issue raised by @krassowski is that the link list on this site ...
... is not in sync with the competing link list on the RTD site.
If the maintainers here would prefer, I could submit patch to the RTD site expanding it to include the links on this site before this patch is merged.