Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial Documentation working group charter #198

Merged
merged 14 commits into from
Jan 16, 2024
50 changes: 50 additions & 0 deletions charters/DocumentationCharter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Documentation Working Group Charter

## Mission and Goals

The Documentation Working Group ("Docs Working Group") serves as a support, helper, and advisory body to Jupyter Subprojects on all aspects of documentation. The core pillars of our mission:

- Improve all aspects of documentation across the Jupyter ecosystem.
- Make high quality documentation that is clear, comprehensive, inclusive, and serves the varying needs of Jupyter's diverse community.
- Engage with the community to help users with Jupyter products, discover their needs, and connect them with relevant information, expertise and resources.

The Docs Working Group will provide a place for consistent, focused, holistic efforts to be spent on documentation across the whole ecosystem. This group exists in part to provide capacity and resources to the subprojects (some of which are already suffering from a lack of resources/capacity, and more specifically to work on documentation in particular).

We want all users to have positive experiences inside the Jupyter ecosystem, especially users who are learning and coming in for the first time, and users with disabilities.

## Areas of Responsibility

The Docs Working Group is responsible for the following:

- Setting standards for documentation where needed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are standards "binding" for sub-projects or are they more like shared resources that sub-projects can use if they wish?

An example - in the JupyterHub project we have a shared modification of the PyData Sphinx Theme defined here:

https://github.com/jupyterhub/jupyterhub-sphinx-theme

This allows JupyterHub projects to use the theme in order to standardize the look and feel across sub-projects. But it's not a "requirement" - it's just a shared resource to be used as is useful.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The vision I have for this: The PyData Sphinx theme could be further developed by the Docs Working Group, in consultation/collaboration with the JupyterHub team and existing devs, then we could take point on advocating for it, both as a resource to teams that need it, and as a standard to make things consistent across the ecosystem.

This collaborative pattern is at the heart of how the Docs Working Group will operate (we help, we do work, we collaborate to understand needs and get feedback, we build resources that other teams can use, and we advocate for their usage to subprojects in accordance with our mission to make the Jupyter ecosystem better and more consistent).

If we do our work right, we will have gathered needs from the subprojects that inform what the theme is capable of, so that they have what they need for that resource to make sense for their project.

Copy link
Contributor

@choldgraf choldgraf Dec 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd love to see this working group be a source of more focused development (or even just specific requests) in the PyData theme (or the sphinx book theme). Those are both chronically under-supported and maintainer-led projects!

If we do our work right, we will have gathered needs from the subprojects that inform what the theme is capable of, so that they have what they need for that resource to make sense for their project.

I like the idea of framing this group as doing a bit of "user research and product development" where the users are Jupyter maintainers that want help with their docs, and the product is infrastructure that makes it happen.

- The Docs working group will take ownership of documentation and related resources not owned by a Subproject.
- Including the Jupyter.org documentation (under docs.jupyter.org/).

## Doumentation Working Group's Activities

The Docs Working Group will focus on the efforts described below, in service of its mission:

- Help write documentation (inside the bounds of each Subproject's governance) including meta documentation, cross-cutting documentation (items relevant to multiple Subprojects), developer and contributor documentation, non user-facing documentation and others.
- Develop recommendations and guidance for best practices surrounding documentation authoring, communication of information, concepts and styling, to promote consistency across the Jupyter ecosystem.
- Community engagement to help connect users with information, expertise, and resources; and to gather feedback from the community about what needs to be documented/what information they need.
- Help support and improve all aspects of documentation across the Jupyter ecosystem: our scope also includes any tasks - beyond writing documents - that will support the Doumentation Working Group's goals. To help illustrate the scope of our work, some clarifying examples are included below:
- Improving the user experience inside Jupyter applications by implementing offline and interactive documentation extensions.
- Implementing analytics systems for documentation webpages for better understanding of documentation usage.
- Any other innovations or work that may improve Jovyans' experience in/understanding of the Jupyter ecosystem.

## Founding Members

- Carlos Brandt
- Carol Willing
- Eric Gentry
- Frederic Collonval
- Michał Krassowski
- Nick Bollweg
- Paul Ivanov
- Rosio Reyes

## Decision Making

The Docs Working Group will establish a council (by Jupyter convention) to make decisions.

The Docs Working Group Council will initially be made up of the founding members. Council members can then initiate a vote to add new members (or remove members by a two thirds majority with a quorum of two thirds of all council members). The voting process will follow the guidelines established in the [Jupyter Governance Decision Making document](https://jupyter.org/governance/decision_making.html).
5 changes: 5 additions & 0 deletions list_of_standing_committees_and_working_groups.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,8 @@ Charter Summary: License, protect, and promote the trademarks and visual and tex
### Jupyter Media Strategy

[Charter](charters/MediaStrategyCharter.md) Summary: Ensure that communications in Jupyter official channels are strategic and benefit Project Jupyter.


### Jupyter Documentation

[Charter](charters/DocumentationCharter.md) Summary: Serve as a support, helper, and advisory body to assist in improving all aspects of documentation across Jupyter subprojects.
Loading