Refactor functional area overview (#658)

.gitignore

@@ -5,3 +5,6 @@ tmp/
 .DS_Store
 .nox
 __pycache__
+
+# Assets generated at build
+_data/tmp

_data/support_stewards/gen_support_stewards.py

@@ -1,4 +1,5 @@
 import os
+import sys
 from collections import OrderedDict
 from pathlib import Path
 from textwrap import dedent
@@ -12,7 +13,7 @@ class SlackUsergroupMembers:
     def __init__(self):
         token = os.environ.get("SLACK_BOT_TOKEN", None)
         if token is None:
-            print("SLACK_BOT_TOKEN does not exist. Skipping Support Steward table generation...")
+            raise ValueError("SLACK_BOT_TOKEN does not exist. Skipping Support Steward table generation...")
 
         self.client = WebClient(token=token)
 
@@ -97,16 +98,26 @@ def get_users_in_usergroup(self, usergroup_name):
 
 
 def main():
-    # Get support stewards usernames and avatars
-    slack = SlackUsergroupMembers()
-    usernames_and_avatars = slack.get_users_in_usergroup("support-stewards")
-
     # Create a tmp dir and set filepaths
-    project_root = Path(__file__).resolve().parent.parent.parent
-    tmp_dir = project_root.joinpath("tmp")
+    path_data_root = Path(__file__).resolve().parent.parent
+    tmp_dir = path_data_root.joinpath("tmp")
     tmp_dir.mkdir(parents=True, exist_ok=True)
     support_stewards_file = tmp_dir.joinpath("support-stewards.txt")
 
+    # Get support stewards usernames and avatars
+    try:
+        slack = SlackUsergroupMembers()
+    except ValueError as err:
+        # If we error, create a blank file so that Sphinx doesn't error on the {include}
+        if not support_stewards_file.exists():
+            support_stewards_file.write_text("```{warning} Slack data did not download.\n```")
+        print("Generating support stewards gallery encountered an error:")
+        print(err)
+        sys.exit()
+    usernames_and_avatars = slack.get_users_in_usergroup("support-stewards")
+
+
+
     # Begin MyST definition of grid with cards
     grid_md = dedent("""
         `````{{grid}} 1 2 3 3

administration/index.md

@@ -4,6 +4,7 @@ This chapter contains administrative information at 2i2c.
 
 ```{toctree}
 :maxdepth: 2
+overview
 structure
 css
 reimburse

administration/overview.md

@@ -0,0 +1,11 @@
+# Scope and responsibilities
+
+Our administration is tasked with carrying out ongoing activities that are required for 2i2c to functiona as an organization.
+This includes:
+
+- Carrying out payments to team members
+- Reimbursing our expenses
+- Overseeing contracting with partner communities and collaborators
+- Overseeing grants and reporting requirements
+- Overseeing invoicing for partner communities that pay us
+- Accounting and some fiduciary oversight

administration/structure.md

@@ -1,18 +1,9 @@
-# Structure and responsibilities
+# Structure and roles
 
-## Scope and responsibilities
+2i2c's administration is largely provided as a service by various partners of 2i2c.
+See below for more information
 
-Our administration is tasked with carrying out ongoing activities that are required for 2i2c to functiona as an organization.
-This includes:
+## Fiscal Sponsor
 
-- Carrying out payments to team members
-- Reimbursing our expenses
-- Overseeing contracting with partner communities and collaborators
-- Overseeing grants and reporting requirements
-- Overseeing invoicing for partner communities that pay us
-- Accounting and some fiduciary oversight
-
-## Team structure and roles
-
-2i2c's administration is largely provided as a service by {term}`CS&S`.
+Our Fiscal Sponsor, {term}`CS&S`, provides back-end administration and support for many of 2i2c's operations.
 See [](css.md) for more information.

communication/index.md

@@ -3,6 +3,7 @@
 These sections describe our external communications strategy and operations.
 
 ```{toctree}
+overview
 strategy
 blog
 social

communication/overview.md

@@ -0,0 +1,4 @@
+# Scope and responsibilities
+
+Our communication area covers our strategy, policy, and systems for communicating with external stakeholders.
+This includes social media, blogs, newsletters, etc.

community/index.md

@@ -9,6 +9,7 @@ See [this blog post](https://2i2c.org/blog/2022/job-product-community-lead/) for
 :::
 
 ```{toctree}
+overview
 structure
 workflow
 freshdesk

community/overview.md

@@ -0,0 +1,20 @@
+# Scope and responsibilities
+
+Our community guidance area ensures that 2i2c's partner communities have the guidance and skills to have impact via our infrastructure and services, and that they can share these skills without being dependent on 2i2c.
+It oversees our content creation and training efforts for partner communities.
+It also oversees our systems for communication and interaction with partner communities.
+
+:::{admonition} Work in progress
+We are still understanding how this area fits in with 2i2c, and the responsibilities and structure of this area may change.
+:::
+
+## Content creation and training
+
+- Oversee user-facing documentation for [our Managed Hub Service](https://docs.2i2c.org).
+- Oversee training material and 2i2c-led events for training.
+
+## Community management with partner communities
+
+- Oversee systems for communication between community partners and 2i2c.
+- Oversee training for communities to self-organize in a sustainable manner (for 2i2c and for communities).
+

community/roles/partnerships-community-lead.md

@@ -0,0 +1,72 @@
+```{role} Product and Community Lead
+```
+
+# Product and Community Lead
+
+There are three key goals for this role:
+
+- Empower the communities we serve to have impact with our infrastructure.
+- Guide our development and service design to reflect the needs of our users.
+- Develop the organizational strategy and structure needed to accomplish these goals within 2i2c.
+
+## Rationale
+
+Solely providing infrastructure to communities via an engineering team is not enough. Working with the modern open source stack, using the cloud to its advantage, and bringing these tools into specific domains requires a lot of extra experience and expertise.
+We believe that 2i2c is in a good position to **provide guidance and support to leaders in the communities that we serve**, allowing them to get up-to-speed with the infrastructure more effectively so that they can have an impact.
+We also believe that it's crucial to **develop infrastructure in collaboration with the communities that we're serving**.
+A team of engineers tends to focus on code and infrastructure, and having a role that focuses on connecting with communities will give them an excellent perspective on what those communities need.
+
+The skills, interests, and career paths for interfacing with communities, guiding them, and participating in design and prioritization efforts with engineers are significantly different from engineering track jobs.
+As such, this role will lead efforts around a new _class_ of jobs within 2i2c: Product and Community.
+
+## Qualities and experience
+
+We are still defining the qualities and experience for this role, but below are a few abstract qualities that will make somebody succeed in this role.
+
+- Demonstrated ability to lead and grow distributed communities of practice (e.g., 3+ years as a leader of an open source community).
+- Demonstrated ability to design and manage technical products (e.g., 3+ years experience as a product manager, or as a product-level lead in an open source community).
+- Demonstrated experience in growing and guiding organizations and teams that do technical development or service work (e.g., 3+ years as a manager or organizational leadership role).
+- Extensive experience with open source workflows, research and educational contexts, and an understanding of the value that hosted infrastructure provides.
+
+## Responsibilities and Expectations
+
+We are still developing the responsibilities and expectations for the role, and will revisit this as we've come to a better understanding of them.
+
+Here is a short list of relevant ideas. Note that this role may do many of these as an "individual contributor" inititally due to our small size, but ultimately the goal is for this role to grow into a leadership and strategy position that may guide and manage others.
+
+- Actively reach out to communities that we serve and learn about their goals and how 2i2c's infrastructure fits into those goals.
+- Actively guide our engineering team's efforts around design and prioritization.
+- Help us consider and discuss trade-offs that we must make in support requests and features.
+- Design and grow structures, spaces, etc for communication between 2i2c and communities we serve, as well as within communities.
+- Lead efforts to provide support for our communities in their use of the infrastructure, and route requests to the engineering team as needed.
+- Lead content creation to empower communities to use our infrastructure more effectively.
+- Define strategy, goals, and assessment criteria for Product and Support.
+- Define roles and job titles for team members that do work in this area, as well as their connections with others on the team.
+- As resources are available, manage and mentor other team members within Product and Community at 2i2c.
+- Interface with the Partnerships Lead to incorporate sustainability in the design and evolution of our services.
+
+## Salary rationale
+
+This is a leadership-level role within 2i2c and focused on Product and Community work. As such we should use the GuideStar salary criteria for the “top” position in a relevant category. It should be appropriate for an early-mid career leader who has demonstrated some experience in the organizational aspects needed to succeed in this role.
+
+We'll plan to use the **Top Program Position** job category within GuideStar to define the base salary for this role. The median base salary for this role is $122,000 as of now (mid-2022).
+
+## Appendix: Inspiration for the role
+
+Here are a few roles that provided inspiration for this position:
+
+- **Product Manager**: Understand the communities that we work with, and to use this to help us make decisions about what to build, how to present it, and how to engage with stakeholders. Help us prioritize the work that is most impactful for our mission, and help us navigate trade-offs in the evolution of our services.
+- **Developer Advocate**: Guide and teach those in the communities we serve - particularly community leaders that go on to teach others - in how to use our infrastructure most-effectively.
+- **Research Applications Manager**: The [**Research Applications Manager**](https://the-turing-way.netlify.app/collaboration/research-infrastructure-roles/ram.html) is a role that has been pioneered by the Turing Institute, and is similarly described as a connector that brings together many perspectives and encourages a participatory, team-based approach to research.
+
+Other comparable titles:
+
+- Community Success Lead
+- Community Impact Lead
+- Director of Community Impact
+- Director of Community Success
+- Infrastructure Applications Lead
+- Product Manager
+- Community Success Lead
+- Infrastructure Impact Lead
+- Community Advocate Lead

community/structure.md

@@ -1,94 +1,17 @@
-# Structure and responsibilities
+# Structure and roles
 
 :::{note}
 This is still a work in progress!
 :::
 
-## Responsibilities
+The Community team at 2i2c is led by our {role}`Product and Community Lead`.
 
-Ensure that 2i2c's partner communities have the guidance and skills to have impact via our infrastructure and services, and that they can share these skills without being dependent on 2i2c.
-
-## Structure
-
-Currently the Community team at 2i2c is made up of one {role}`Community Guidance Lead`, who collaborates closely with the {role}`Partnerships Lead` in planning and coordination.
-
-They also collaborate with our [Engineering Team](../engineering/structure.md) to bring community perspectives into our planning and prioritization.
+Below are major roles and teams...
 
 ## Roles
 
-```{role} Product and Community Lead
+```{toctree}
+:glob:
+:maxdepth: 2
+roles/*
 ```
-
-### Product and Community Lead
-
-There are three key goals for this role:
-
-- Empower the communities we serve to have impact with our infrastructure.
-- Guide our development and service design to reflect the needs of our users.
-- Develop the organizational strategy and structure needed to accomplish these goals within 2i2c.
-
-#### Rationale
-
-Solely providing infrastructure to communities via an engineering team is not enough. Working with the modern open source stack, using the cloud to its advantage, and bringing these tools into specific domains requires a lot of extra experience and expertise.
-We believe that 2i2c is in a good position to **provide guidance and support to leaders in the communities that we serve**, allowing them to get up-to-speed with the infrastructure more effectively so that they can have an impact.
-We also believe that it's crucial to **develop infrastructure in collaboration with the communities that we're serving**.
-A team of engineers tends to focus on code and infrastructure, and having a role that focuses on connecting with communities will give them an excellent perspective on what those communities need.
-
-The skills, interests, and career paths for interfacing with communities, guiding them, and participating in design and prioritization efforts with engineers are significantly different from engineering track jobs.
-As such, this role will lead efforts around a new _class_ of jobs within 2i2c: Product and Community.
-
-#### Qualities and experience
-
-We are still defining the qualities and experience for this role, but below are a few abstract qualities that will make somebody succeed in this role.
-
-- Demonstrated ability to lead and grow distributed communities of practice (e.g., 3+ years as a leader of an open source community).
-- Demonstrated ability to design and manage technical products (e.g., 3+ years experience as a product manager, or as a product-level lead in an open source community).
-- Demonstrated experience in growing and guiding organizations and teams that do technical development or service work (e.g., 3+ years as a manager or organizational leadership role).
-- Extensive experience with open source workflows, research and educational contexts, and an understanding of the value that hosted infrastructure provides.
-
-#### Responsibilities and Expectations
-
-We are still developing the responsibilities and expectations for the role, and will revisit this as we've come to a better understanding of them.
-
-Here is a short list of relevant ideas. Note that this role may do many of these as an "individual contributor" inititally due to our small size, but ultimately the goal is for this role to grow into a leadership and strategy position that may guide and manage others.
-
-- Actively reach out to communities that we serve and learn about their goals and how 2i2c's infrastructure fits into those goals.
-- Actively guide our engineering team's efforts around design and prioritization.
-- Help us consider and discuss trade-offs that we must make in support requests and features.
-- Design and grow structures, spaces, etc for communication between 2i2c and communities we serve, as well as within communities.
-- Lead efforts to provide support for our communities in their use of the infrastructure, and route requests to the engineering team as needed.
-- Lead content creation to empower communities to use our infrastructure more effectively.
-- Define strategy, goals, and assessment criteria for Product and Support.
-- Define roles and job titles for team members that do work in this area, as well as their connections with others on the team.
-- As resources are available, manage and mentor other team members within Product and Community at 2i2c.
-- Interface with the Partnerships Lead to incorporate sustainability in the design and evolution of our services.
-
-#### Salary rationale
-
-This is a leadership-level role within 2i2c and focused on Product and Community work. As such we should use the GuideStar salary criteria for the “top” position in a relevant category. It should be appropriate for an early-mid career leader who has demonstrated some experience in the organizational aspects needed to succeed in this role.
-
-We'll plan to use the **Top Program Position** job category within GuideStar to define the base salary for this role. The median base salary for this role is $122,000 as of now (mid-2022).
-
-#### Appendix: Inspiration for the role
-
-Here are a few roles that provided inspiration for this position:
-
-- **Product Manager**: Understand the communities that we work with, and to use this to help us make decisions about what to build, how to present it, and how to engage with stakeholders. Help us prioritize the work that is most impactful for our mission, and help us navigate trade-offs in the evolution of our services.
-- **Developer Advocate**: Guide and teach those in the communities we serve - particularly community leaders that go on to teach others - in how to use our infrastructure most-effectively.
-- **Research Applications Manager**: The [**Research Applications Manager**](https://the-turing-way.netlify.app/collaboration/research-infrastructure-roles/ram.html) is a role that has been pioneered by the Turing Institute, and is similarly described as a connector that brings together many perspectives and encourages a participatory, team-based approach to research.
-
-Other comparable titles:
-
-- Community Success Lead
-- Community Impact Lead
-- Director of Community Impact
-- Director of Community Success
-- Infrastructure Applications Lead
-- Product Manager
-- Community Success Lead
-- Infrastructure Impact Lead
-- Community Advocate Lead
-
-## Membership
-
-See [list of team members](../reference/team.md).

conf.py

@@ -92,12 +92,10 @@ def setup(app):
     app.add_crossref_type("team", "team")
 
 # -- Generate table of Support Stewards --------------------------------------
-# This script requires the use of a token that is stored in the ReadTheDocs
-# environment. Hence let's only execute it if we are in an RTD build
-READTHEDOCS = os.environ.get("READTHEDOCS", False)
-if READTHEDOCS:
-    path_script = Path(__file__).parent / "_data/support_stewards/gen_support_stewards.py"
-    run(f"python {path_script}", shell=True)
+# This requires a token to be set, but will fail semi-gracefully if it is not.
+# The token exists in our RTD environmet so it should work there.
+path_script = Path(__file__).parent / "_data/support_stewards/gen_support_stewards.py"
+run(f"python {path_script}", shell=True)
 
 # -- Options for the rediraffe extension -------------------------------------
 # ref: https://github.com/wpilibsuite/sphinxext-rediraffe#readme

engineering/index.md

@@ -3,9 +3,10 @@
 These sections have information about accounts, technology, and practices that are specifically related to our team's infrastructure.
 
 ```{toctree}
+overview
 structure
-strategy
 workflow
+strategy
 access
 secrets
 reviewing

engineering/overview.md

@@ -0,0 +1,20 @@
+# Scope and responsibilities
+
+Engineering is responsible for all of our technical infrastructure, and for the teams and processes around cloud infrastructure for our **Managed JupyterHub Service**.
+
+## Oversee our technical strategy
+
+- Define our major objectives and priorities.
+- Make major architectural decisions about our cloud infrastructure.
+
+## Operate our cloud infrastructure
+
+- Perform daily operation of ongoing cloud services, addressing technical problems as-needed.
+- Resolve operational issues related to our cloud infrastructure.
+- Oversee our [Incident Response process](../projects/managed-hubs/incidents.md).
+
+## Develop our cloud infrastructure
+
+- Improve the reliability and uptime of our infrastructure
+- Improve the scalability of our infrastructure to more users and more communities
+- Minimize toil and automate processes as much as possible

engineering/reviewing.md

@@ -37,10 +37,3 @@ Not all of them are followed strictly, though some are more important than other
 Changing active infrastructure is a bit different from developing technology that is not immediately in production.
 As such, we follow some more specific guidelines for these kinds of changes.
 See {ref}`infra:infrastructure:review`.
-
-## Policy for team compass changes
-
-If a change affects the 2i2c team policies, or makes significant changes to our documentation or public-facing material, then you should also follow these extra policies:
-
-- **Ensure that the team has consented**.
-  For any major change, you should make sure that you have followed best-practices in consent-based decision making. See [](development:decisions) for more information.