jupyterhub · consideRatio · Nov 25, 2022 · Nov 23, 2022 · Nov 23, 2022 · Nov 24, 2022
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -1,3 +0,0 @@
-.contributor-grid .sd-card-text {
-    margin-bottom: 0;
-}

diff --git a/docs/building-blocks/index.rst b/docs/building-blocks/index.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,109 +1,32 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# Team Compass documentation build configuration file, created by
-# sphinx-quickstart on Sun Dec  3 20:44:20 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 
 # -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ['sphinx_copybutton', "sphinx_design", 'sphinx.ext.mathjax', 'myst_parser']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-source_suffix = ['.rst']
-
-# The master toctree document.
-master_doc = 'index'
+extensions = ["sphinx_copybutton", "sphinx_design", "sphinx.ext.mathjax", "myst_parser"]
+templates_path = []
+source_suffix = [".rst", ".md"]
+root_doc = "index"
 
 # General information about the project.
-project = 'Team Compass'
-copyright = '2022, JupyterHub Team and Binder Team'
-author = 'JupyterHub Team and Binder Team'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '1.0'
-# The full version, including alpha/beta/rc tags.
-release = '1.0'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+project = "Team Compass"
+copyright = "2022, JupyterHub Team and Binder Team"
+author = "JupyterHub Team and Binder Team"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 def setup(app):
     app.add_css_file("custom.css")
 
 
 # -- Options for HTML output ----------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'pydata_sphinx_theme'
-
-# Logo
-html_logo = '_static/logo.png'
-html_favicon = '_static/favicon.png'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_theme = "pydata_sphinx_theme"
+html_logo = "_static/logo.png"
+html_favicon = "_static/favicon.png"
+html_static_path = ["_static"]
 html_theme_options = {
     "use_edit_page_button": True,
-    "google_analytics_id": "UA-101904940-3",
+    "analytics": {
+        "google_analytics_id": "UA-101904940-3",
+    },
     "github_url": "https://github.com/jupyterhub/team-compass",
     "twitter_url": "https://twitter.com/projectjupyter",
     "icon_links": [
@@ -112,18 +35,19 @@ def setup(app):
             "url": "https://discourse.jupyter.org/c/jupyterhub/10",
             "icon": "fab fa-discourse",
         }
-   ],
-   "navbar_end": ["navbar-icon-links"],
+    ],
 }
 
 html_context = {
     "github_user": "jupyterhub",
     "github_repo": "team-compass",
-    "github_version": "master",
-    "doc_path": "doc",
+    "github_version": "main",
+    "doc_path": "docs",
     "source_suffix": source_suffix,
 }
 
 # -- Update contributor lists --------------------------------------------
+
 from subprocess import run
-run(['python', '_data/contributors/gen_contributors.py'], check=True)
+
+run(["python", "_data/contributors/gen_contributors.py"], check=True)
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
diff --git a/docs/contribute/skills.md b/docs/contribute/skills.md
@@ -1,4 +1,4 @@
-# Skills and ways to contribute
+# Useful skills and ways to contribute
 
 There are many ways that you can contribute to the JupyterHub / Binder projects.
 This page suggests some pathways for community members to learn new skills and
@@ -112,13 +112,12 @@ all obvious. If you'd like to make a contribution and you're not sure where to s
 a good rule of thumb is to open an issue or reach out to another team member to help
 you scope the work you'd like to do, and to set expectations.
 
-## Links
-
-* The [UC Berkeley JupyterHubs documentation](https://docs.datahub.berkeley.edu/en/latest/pre-reqs.html)
-  has a similar scope and set of information.
-
-## Resources for Learning
+## Resources for learning
 
 In this section, we gather some introductory materials for learning the aforementioned tools.
 
-- **[Learning-k8s](https://github.com/knrt10/kubernetes-basicLearning)**: A step-by-step guide to learning the basics of Kubernetes
+* The [UC Berkeley JupyterHubs documentation](https://docs.datahub.berkeley.edu/en/latest/pre-reqs.html)
+  has a similar scope and set of information.
+* **[Learning-k8s](https://github.com/knrt10/kubernetes-basicLearning)**: A step-by-step guide to learning the basics of Kubernetes
+* [**The mybinder SRE guide**](https://mybinder-sre.readthedocs.io/en/latest/) is a set of resources for running mybinder.org.
+  It contains tips, snippets, lessons-learned etc for running a large, public kubernetes cluster.
diff --git a/docs/index-team_governance.rst b/docs/index-team_governance.rst
diff --git a/docs/index-team_guides.rst b/docs/index-team_guides.rst
@@ -1,17 +1,32 @@
 .. _guides_index:
 
-==============
-Team Resources
-==============
+=====================
+Contributor resources
+=====================
 
 Resources and guides for team members to help us coordinate and work together more effectively.
 
-.. toctree::
+**Contributor guide** is a resource for those interested in learning more about JupyterHub and how they can contribute to this project.
 
-   team/member-guide
-   team/repository-code-standards
-   team/adding-members
-   team/shared-infrastructure
-   talking
-   building-blocks/index
-   team/community-strategy
+Our project depends on contributions from volunteers across the world who are interested in supporting the JupyterHub Project.
+The sections below provide some resources to help you get started contributing to our community.
+
+.. toctree:: 
+   :caption: Contributor guide
+   :maxdepth: 2
+
+   contribute/guide
+   contribute/skills
+
+**Team information** is meant to share information and context across team members, and align us on a plan of action.
+
+.. toctree:: 
+   :caption: Team information
+   :maxdepth: 2
+
+   meetings/index
+   resources/shared-infrastructure
+   resources/binder-infrastructure
+   resources/milestones
+   contribute/repository-info
+   resources/community-strategy
diff --git a/docs/index-team_policies.rst b/docs/index-team_policies.rst
@@ -0,0 +1,33 @@
+Team policies and standards 
+===========================
+
+**Governance and structure** defines our decision-making policies, how we organize ourselves, and the practices that we commit to following.
+
+.. toctree:: 
+   :caption: Governance and structure
+   :maxdepth: 2
+
+   governance
+   binder/subdomains
+   team/structure
+   Jupyter Code of Conduct <https://jupyter.org/governance/conduct/code_of_conduct.html>
+
+**Team practices** describe our operational policies and practices.
+
+.. toctree::
+   :caption: Team practices
+   :maxdepth: 2
+
+   practices/communication
+   practices/adding-members 
+   practices/talking
+   practices/check-ins
+
+**Technical practices** describe our standards and processes around technical infrastructure.
+
+.. toctree::
+   :caption: Technical practices
+
+   practices/merging
+   practices/repository-code-standards
+   practices/readme-badges
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,13 +10,11 @@ Team Compass for JupyterHub and Binder
    :target: https://hackmd.io/u2ghJJUCRWK-zRidCFid_Q?view
    :alt: monthly agenda
 
-This page contains links to the notes from team meetings
-with the JupyterHub community. For more some more technical information
-and links to various JupyterHub repositories, see the
-`Team Compass README <https://github.com/jupyterhub/team-compass>`_.
+Our Team Compass contains team practices, policies, and resources to help one another align and contribute.
+It also has helpful information for team members, like shared infrastructure and accounts, resources to learn how to contribute, etc.
 
-Team Compass Resources
-======================
+We use [**Team Compass issues**](https://github.com/jupyterhub/team-compass/issues)
+to discuss specific, actionable things related to the *team* (e.g., discussing whether to change something in the team-compass repo).
 
 The following pages contain information about the JupyterHub/Binder
 teams, resources for community members, and team practices for
@@ -26,16 +24,14 @@ governance and planning.
    :maxdepth: 2
 
    team/index
+   index-team_policies
    index-team_guides
-   index-team_governance
-   contribute/index
 
 Why have a Team Compass?
 ========================
 
-This repository helps the JupyterHub team and Binder team set a weekly
-course for project activity. Our overriding goal is continuous team and
-project improvement.
+This repository helps the JupyterHub team and Binder team align on our structure, policy, and goals.
+Our primary goal is continuous team and project improvement.
 
 As projects and their growth evolve rapidly, the contents of this repo
 should aid us in setting project direction and adjusting the course as

diff --git a/docs/team/adding-members.rst → docs/practices/adding-members.rst b/docs/team/adding-members.rst → docs/practices/adding-members.rst
@@ -14,16 +14,15 @@ expectations and responsibilities.
 For someone to join a team, they should be a consistent,
 positive, productive member of the community.
 Moreover, team members should be interested in
-**continuing their engagement** over a long-ish period of time
+**continuing their engagement** over a long-ish period of time.
 
-.. seealso::
-
-   - :doc:`structure` lists our teams, and the responsibilities and expectations
-     that come with each. See .
-   - :doc:`../contribute/index` is a guide for newcomers who would like to begin contributing.
+They should:
+
+- Be familiar with `our Team Practices and Policies <../practices/index>`_
+- Be willing to commit to `the responsibilities that come with team membership <../practices/responsibilities>`_
 
-General process for adding team members
-=======================================
+Process for adding team members
+===============================
 
 Any new team members must be "championed" by a pre-existing team member. This
 is a person who recommends that the new person be invited to join the team.
@@ -34,7 +33,7 @@ This process takes the following steps:
    the process.
 2. If there seems to be team consensus,
    the champion contacts the potential new team member and ask if they are
-   interested. Don't forget to run them by the responsibilities in the :doc:`structure`
+   interested. Don't forget to run them by the responsibilities in the :doc:`../team/structure`
    page to make sure they understand what they're signing up for.
    If so, then move to the next step.
 3. The champion opens a new issue in the `team compass repository <https://github.com/jupyterhub/team-compass>`_.