Jupyter needs better documentation, and we need your help to make it happen! A new Jupyter Documentation Working Group is being formed to make documentation better across all of Jupyter, and not all of the work is writing docs, so if you’re interested in any of these focus areas or early tasks, please stop by the Github issue (link here) and leave a comment that expresses “I’m interested!”:
Possible major focuses:
Content (writing docs)
Discovery/community engagement (getting users info they need)
Feedback (what needs to be documented? what info do people need?)
Potential early work targets:
Characterize documentation needs across subprojects (what needs to be added, improved, made consistent across each)
Capture/store (possibly automate) readthedocs traffic stats/CSVs for last 90 days on a regular basis to get rough metrics on what’s important to users
Add some easy CI tests to ensure commands in the tutorial run without erroring (would have helped prevent the docs from breaking this time as mentioned above), other CI tests
“Get Help” effort spanning multiple subprojects, to consistently communicate to users how they can get help from Jupyter stakeholders/developers/resources, on each subproject’s documentation site
Document insights from recent issues/bugs (such as the Homebrew bug)
And more!
Read more about the new Documentation Working Group here, we’d love to have your perspectives and expertise as we get this new working group started. Thanks to everyone who can join in!
I don’t know if you are seeking ideas or only spreading the word, but I think that maybe implementing a footer like on docs.github.com could be a good first step to gather some data on docs needs:
Just a note that I really support something like this. I am not sure whether I have the capacity to commit to something in an ongoing basis, but I am happy to provide strategic insight wherever I can, or unblock things that need to move forward.
The JupyterHub team has recently adopted a lightweight customized version of the PyData Sphinx Theme here:
Perhaps something like this could be generalized to Jupyter in a way that is still customizable for many different repositories and sub-projects? I have a fair bit of knowledge for how Sphinx and the theme work in general so am happy to advise.
I’d also love to see more Jupyter participation in development for the pydata-sphinx-theme in general:
And finally, there’s growing momentum in the MyST Markdown ecosystem to provide a Javascript-based documentation engine, and this might have a lot of interesting tie-ins with other Jupyter sub-projects:
So broadly I’m just voicing my support for having more cross-communication and collaboration around Jupyter regarding documentation. I think it’s a really low-hanging fruit to improve the quality of user pathways through this ecosystem.
On top of the MyST suggestion, we could (or should) look into integrating Jupyter-Book in the loop. Especially regarding the point of testing code in the docs.
@choldgraf Apologies for the delay, for the pydata-sphinx-theme, are there some benefits from this version that you think we can bring to the other subprojects? These could be fleshed out into github issues. Would also be interested to hear more about MYST.
Would you like to join as a founding member of the Docs Working Group? As someone involved in docs and the community, we could use your thoughts and experience!
