Initial Documentation working group charter #198
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # Docs Working Group Charter (Proposed) | ||
|
|
||
| ## Mission and Goals | ||
|
|
||
| The 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: | ||
RRosio marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. I love these pillars :-) We have needed this in the community for a long time, really appreciate everyone who is stepping up to help. |
||
|
|
||
| - 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 | ||
RRosio marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - 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 docs 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 docs 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. | ||
|
|
||
| ## The Docs Working Group's Activities | ||
|
There was a problem hiding this comment. There maybe room for two sections here (responsibilities and activities). For some things I think the WG should own and have a responsibility for something. For other things, their role is more of a helper for subprojects where activity is maybe a better term. |
||
|
|
||
| The Docs Working Group will focus on the efforts described below, in service of its mission: | ||
|
|
||
| - Help write docs (inside the bounds of each subproject's governance) | ||
RRosio marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. One question that I have is that Jupyter has some documentation that isn't (currently) part of subprojects. Will this WG own that documentation? Right now this type of documentation is in the grey area of the project where it isn't clear who can even review/merged PRs. I think it would be helpful if the charter gave the WG ownership of those docs. |
||
| - This includes meta docs, cross-cutting docs (items relevant to multiple subprojects), developer and contributor docs, non user-facing docs and others | ||
RRosio marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Develop recommendations and guidance: | ||
| - For communicating common information and concepts across the Jupyter ecosystem | ||
| - Because we want to encourage consistency across the Jupyter ecosystem and between different projects | ||
| - For style and best practices when authoring documentation media | ||
| - Including technical advice, such as tools-usage and markdown guidance that helps support high level goals, like interlinking/cross-connection between subprojects | ||
| - Community engagement | ||
| - To help connect users with information, expertise and resources | ||
RRosio marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - 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 | ||
| - This means, for members of the group, also taking on any related (non-document) tasks that will be beneficial to docs and support the Docs Working Group's goals, such as: | ||
| - Developing application extensions related to docs, like in-app integrated docs, guided in-application tours or hoverable "what's this" features | ||
| - Automations for gathering ReadTheDocs traffic stats to gauge user interest | ||
|
There was a problem hiding this comment. Some of these seem a bit too technical and specific to be included in the charter, I'd suggest being more high level and tool agnostic. There was a problem hiding this comment. How about this @blink1073 ?
There was a problem hiding this comment. I think the important part here is "This means...also taking on any related (non-document) tasks", to explicitly call out that our scope includes development work and other non-writing work that supports the mission. Most of these items are intended to be clarifying examples that illustrate the intended meaning. I do take your point about being tool-agnostic though... @chbrandt I think that looks good. |
||
| - Creating pip installable packages for getting offline docs | ||
| - Writing PRs for unit tests related to documentation code | ||
| - Automated discourse or CI bots for gathering user feedback from community sites | ||
| - Adding a new embedded "Hot Topics" feature on ReadTheDocs FAQ pages to automated discourse community discussion aggregator | ||
|
There was a problem hiding this comment. I don't have an objection to this at all, but I'd remove it from the charter and instead create an issue on the docs working group repo and handle it as a task instead of a chartered mandate. |
||
| - 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 | ||
| - Mike Krassowski | ||
RRosio marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - 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). | ||
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.
In the Jupyter ecosystem, the term "doc" has a number of different meanings (notebook docs, documentation, etc.). It may be helpful to spell out "Documentation" in the charter to clarify this to people who may not have full context.