-
Notifications
You must be signed in to change notification settings - Fork 71
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
+55
−0
Merged
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
fd72bf2
Initial Documentation working group charter
RRosio edaf7d6
Update charters/DocumentationCharter.md
RRosio a034362
Update charters/DocumentationCharter.md
RRosio 74e87a0
Update charters/DocumentationCharter.md
RRosio 3cfe9ea
Update charters/DocumentationCharter.md
RRosio 6636f95
WIP updates as per EC meeting
RRosio 429d5e9
Update charters/DocumentationCharter.md
RRosio 09bd4d0
Edits to areas of responsibilities.
RRosio 54e4099
Minor formatting updates.
RRosio ef93af2
More minor formatting updates.
RRosio aaf0076
Additional formatting updates.
RRosio 0adb09e
Additional updates to formatting.
RRosio 5771bb1
Additional updates to format.
RRosio d3869c0
additional updates based on feedback
RRosio File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. | ||
- 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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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!
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.