A New Documentation Working Group #212
Description
Summary
As discussed in the JupyterLab weekly meeting, this issue proposes a new Jupyter Documentation working group, to coordinate docs work across the entire Jupyter ecosystem (Notebook, Lab, Server, etc.).
Why make a working group?
Repeated and recent docs breakages have made clear the need for focused and coordinated work across subprojects, to ensure that users are not turned away from the Jupyter ecosystem because of bad early experiences from untended documentation. Distributed docs efforts per subproject also produce content with disparate structure and quality, even when common information is being explained.
By coordinating docs work across the ecosystem and regularly focusing efforts on docs quality, we can achieve better consistency and quality across subprojects, help prevent docs bugs and errors due to core code drift, and help the community by increasing discovery and access to information they need, and helping to identify information that needs to be added.
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)
- Look at the wishlist issue and forum post for tasks to bring in
- Add a footer to docs pages, etc.
- 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!
What can I do?
If you're interested in working on docs efforts, leave a comment below to express your interest. When we have enough interest, we can start next steps in officially forming the working group.
Resources
The jupyter/docs repo holds the draft group charter, meeting minutes, etc.
https://github.com/jupyter/docs
First meeting
(This section will be kept updated with current planning around the first meeting)
A first meeting date/schedule has been (tentatively) decided! It will be weekly, on Wednesday at 11am EST, starting October 4th (2 weeks from this post). This is an open call, so (anyone) please join if you're interested :)
Agenda:
- Discuss: Documentation Working Group charter
- Begin early docs work / planning
- Plan for next steps / formal recognition of the working group
- Create a team compass and adapt Jupyter resources (code of conduct/governance, etc.)
Mentions: @chbrandt @JasonWeill
See also: