restructuring documentation and updating information

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

151 stars 103 forks source link

restructuring documentation and updating information #213

Closed choldgraf closed 3 years ago

choldgraf commented 3 years ago

This is a medium-sized restructuring and update of the Binder user documentation. It has the following aims:

Reorganize so we have less duplicated information and more natural clustering of information
Put section files in folders so it's easier to track and maintain
Update content about the deployments/federation, etc (closes #209 closes #195 )
Update content in general to improve the guides and such (closes https://github.com/jupyterhub/binder/issues/200)
Update the logo to make better use of logo space
Add social media icons and links via the theme's config (closes #179)
Uses sphinx panels to more nicely-organize many pages
Updating more pages to markdown instead of rST

would love to hear thoughts! (cc @sgibson91 who helpfully opened several of the issues this tris to tackle...let me know if I missed something!)

consideRatio commented 3 years ago

@choldgraf I think this looks great! I didn't find anything that I wanted to suggest an edit to. I didn't read through all the text, but found a lot of what I read very good. I think for example you did an excellent job in the about page giving a far more friendly introduction than the much more technical one that was around before.

For anyone else looking at this PR; don't miss out on readthedocs PR review feature that gives you a link in the commit checks!

betatim commented 3 years ago

This is a nice PR that implements a lot of issues which is great. It moves content and its adds new content. This makes it hard to see which is which. I'll try and leave a comment on things which I think are new content to call attention to it.

betatim commented 3 years ago

It would be nice to get some feedback on https://github.com/jupyterhub/binderhub/issues/1091 as part of this docs rewrite. I think all documentation that isn't specific to mybinder.org should migrate to the BinderHub documentation.

choldgraf commented 3 years ago

OK I believe that I've addressed all of the comments here - improved a bunch of the language per your suggestions and also added redirects for all of the moved pages with sphinxext.rediraffe.

@betatim I added some comments to the issue about moving the user docs to /binderhub...I think it could be a good idea! Perhaps something we can continue tackling after this round of improvements? I'm happy to keep iterating in the next few weeks.

consideRatio commented 3 years ago

Great work on this everyone! 🥳😍

choldgraf commented 3 years ago

Hey all, anything else for me to do on this one? (and independent of this one, another note that @betatim is looking for feedback in https://github.com/jupyterhub/binderhub/issues/1091 on whether to combine the BinderHub user docs with the BinderHub admin docs)

choldgraf commented 3 years ago

I see lots of 👍 and 🚀 and "approve"s, but nobody has pressed the green button!

consideRatio commented 3 years ago

Thank you for your work om this @choldgraf and everyone for your review help! I love to see these kinds of improvements, but they are a bit scary to merge so i didnt do it myself before - i do think its important to help the PR authors move onwards though so i hit merge now - thanks for nudging with a comment!

choldgraf commented 3 years ago

thanks @consideRatio!