From e69962ad48e296ea80ba9905d2683ff3e2d80b43 Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Wed, 4 Oct 2023 10:49:35 -0400 Subject: [PATCH 1/8] Added initial draft charter. --- charter.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 charter.md diff --git a/charter.md b/charter.md new file mode 100644 index 0000000..2e03cdd --- /dev/null +++ b/charter.md @@ -0,0 +1,26 @@ +The Docs Working Group should exist as a support/helper and advisory group to all the subprojects in Jupyter. Here are some additional details to clarify the WG's scope and role: + +### The WG's scope and role: + +- Help write docs (inside the bounds of each subproject's governance) +- Develop recommendations and guidance: + - For communicating common information and concepts across the Jupyter ecosystem + - 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) + - ...because we want to encourage consistency across the Jupyter ecosystem and between different projects +- Community engagement + - To help connect users with information + - 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 tasks that will be beneficial to docs and support the Docs Working Group's goals (such as writing PRs for unit tests related to documentation code, automations for gathering ReadTheDocs traffic stats, etc.) + +One reason for starting the Docs Working Group is to provide a place for consistent, focused effort to be spent specifically on docs across the whole ecosystem. + +In other words, the Docs Working 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). + +Reflecting on the above, a goal/mission for the group might boil down to: + +### Goals/Mission + +- Help support and 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, and to get them the information they need \ No newline at end of file From 2d40d573c091d785f6756412879a1105df6279d1 Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Thu, 5 Oct 2023 13:56:47 -0400 Subject: [PATCH 2/8] Update charter.md Co-authored-by: Carol Willing --- charter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charter.md b/charter.md index 2e03cdd..00f1e6e 100644 --- a/charter.md +++ b/charter.md @@ -1,6 +1,6 @@ The Docs Working Group should exist as a support/helper and advisory group to all the subprojects in Jupyter. Here are some additional details to clarify the WG's scope and role: -### The WG's scope and role: +## Docs WG's scope and role - Help write docs (inside the bounds of each subproject's governance) - Develop recommendations and guidance: From dd650c3a3e59ccdb94e403220c879f5f3982dc6b Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Thu, 5 Oct 2023 13:58:23 -0400 Subject: [PATCH 3/8] Update charter.md Co-authored-by: Carol Willing --- charter.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/charter.md b/charter.md index 00f1e6e..5d84bd2 100644 --- a/charter.md +++ b/charter.md @@ -1,4 +1,6 @@ -The Docs Working Group should exist as a support/helper and advisory group to all the subprojects in Jupyter. Here are some additional details to clarify the WG's scope and role: +# Docs Working Group Charter (Proposed) + +The Docs Working Group serves to support, assist, and advise Jupyter subprojects on documentation best practices. ## Docs WG's scope and role From d8e4f88eba5d0c2b7e8949679ce124660fc68b35 Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Thu, 5 Oct 2023 14:01:53 -0400 Subject: [PATCH 4/8] Update charter.md Co-authored-by: Carol Willing --- charter.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/charter.md b/charter.md index 5d84bd2..69eed07 100644 --- a/charter.md +++ b/charter.md @@ -1,5 +1,7 @@ # Docs Working Group Charter (Proposed) +## Goals +The Docs Working Group's goals should serve the end users of Jupyter projects. The Docs Working Group serves to support, assist, and advise Jupyter subprojects on documentation best practices. ## Docs WG's scope and role From d8c370bd695dc4b4bd67d06e0b504419bc0b60b8 Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Thu, 5 Oct 2023 14:03:15 -0400 Subject: [PATCH 5/8] Update charter.md Co-authored-by: Carol Willing --- charter.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/charter.md b/charter.md index 69eed07..5ec232b 100644 --- a/charter.md +++ b/charter.md @@ -6,6 +6,10 @@ The Docs Working Group serves to support, assist, and advise Jupyter subprojects ## Docs WG's scope and role +### Improve end-user discoverability of docs +- Create a markdown file that links to all projects and their user-facing documentation (This markdown file will help provide an easy way to link out to the different subproject's docs). + +### Assist subprojects - Help write docs (inside the bounds of each subproject's governance) - Develop recommendations and guidance: - For communicating common information and concepts across the Jupyter ecosystem From 8027be303924051b1bb8c91b35bf54336eaa49af Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Fri, 6 Oct 2023 16:00:14 -0400 Subject: [PATCH 6/8] Reductions, clarifications and reformatting. --- charter.md | 60 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/charter.md b/charter.md index 5ec232b..25650bd 100644 --- a/charter.md +++ b/charter.md @@ -1,34 +1,48 @@ # Docs Working Group Charter (Proposed) -## Goals -The Docs Working Group's goals should serve the end users of Jupyter projects. -The Docs Working Group serves to support, assist, and advise Jupyter subprojects on documentation best practices. +## Mission and Goals -## Docs WG's scope and role +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: -### Improve end-user discoverability of docs -- Create a markdown file that links to all projects and their user-facing documentation (This markdown file will help provide an easy way to link out to the different subproject's docs). +- 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 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 + +The Docs Working Group will focus on the efforts described below, in service of its mission: -### Assist subprojects - Help write docs (inside the bounds of each subproject's governance) + - This includes meta docs, cross-cutting docs (items relevant to multiple subprojects), developer and contributor docs, non user-facing docs and others - Develop recommendations and guidance: - For communicating common information and concepts across the Jupyter ecosystem - - 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) - - ...because we want to encourage consistency across the Jupyter ecosystem and between different projects + - 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 + - To help connect users with information, expertise and resources - 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 tasks that will be beneficial to docs and support the Docs Working Group's goals (such as writing PRs for unit tests related to documentation code, automations for gathering ReadTheDocs traffic stats, etc.) - -One reason for starting the Docs Working Group is to provide a place for consistent, focused effort to be spent specifically on docs across the whole ecosystem. - -In other words, the Docs Working 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). - -Reflecting on the above, a goal/mission for the group might boil down to: - -### Goals/Mission - -- Help support and 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, and to get them the information they need \ No newline at end of file + - 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 + - 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 + - Any other innovations or work that may improve Jovyans' experience in/understanding of the Jupyter ecosystem + +## Insights, Challenges and Opportunities + +This group has identified some insights and challenges (and related opportunities) that will help guide our work: + +- Users often express that it's challenging to get a unified view of "what is Jupyter" and how the components work together. + - We should work to remedy this and provide more explanation and context in appropriate places. +- Jupyter's modular approach (from The Big Split) can make it difficult to communicate the right information in the right place. Insights from one project can be relevant to other subprojects, and some information spans multiple subprojects. + - We should encourage consistency and cross-linking across the Jupyter ecosystem and between different subprojects. + - Create a docs page that links to all projects and their user-facing documentation (This page will help provide an easy way to link out to the different subproject's docs). +- There should be multiple ways to consume docs, through multiple points of delivery. From f411fd8d6ca571d7b648d4f8c1eec7563a12420f Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Wed, 11 Oct 2023 10:57:02 -0400 Subject: [PATCH 7/8] Revised insights. --- charter.md | 1 + 1 file changed, 1 insertion(+) diff --git a/charter.md b/charter.md index 25650bd..9d6100b 100644 --- a/charter.md +++ b/charter.md @@ -46,3 +46,4 @@ This group has identified some insights and challenges (and related opportunitie - We should encourage consistency and cross-linking across the Jupyter ecosystem and between different subprojects. - Create a docs page that links to all projects and their user-facing documentation (This page will help provide an easy way to link out to the different subproject's docs). - There should be multiple ways to consume docs, through multiple points of delivery. +- Plain Language should as much as possible to facilitate inclusivity for people of different backgrounds in the Jupyter community From 27e7883db6ad6ed6a7d8734c02e23b392b83566d Mon Sep 17 00:00:00 2001 From: Eric Gentry Date: Tue, 17 Oct 2023 16:00:02 -0400 Subject: [PATCH 8/8] Moved/removed the insights section. --- charter.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/charter.md b/charter.md index 9d6100b..36f4942 100644 --- a/charter.md +++ b/charter.md @@ -35,15 +35,3 @@ The Docs Working Group will focus on the efforts described below, in service of - 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 - Any other innovations or work that may improve Jovyans' experience in/understanding of the Jupyter ecosystem - -## Insights, Challenges and Opportunities - -This group has identified some insights and challenges (and related opportunities) that will help guide our work: - -- Users often express that it's challenging to get a unified view of "what is Jupyter" and how the components work together. - - We should work to remedy this and provide more explanation and context in appropriate places. -- Jupyter's modular approach (from The Big Split) can make it difficult to communicate the right information in the right place. Insights from one project can be relevant to other subprojects, and some information spans multiple subprojects. - - We should encourage consistency and cross-linking across the Jupyter ecosystem and between different subprojects. - - Create a docs page that links to all projects and their user-facing documentation (This page will help provide an easy way to link out to the different subproject's docs). -- There should be multiple ways to consume docs, through multiple points of delivery. -- Plain Language should as much as possible to facilitate inclusivity for people of different backgrounds in the Jupyter community