[Discovery] New Open edX Handbook Structure

Introduction

This document outlines the structure of the Open edX Handbook, based on survey feedback and existing Core Contributor information. The first phase of this initiative focuses primarily on Core Contributors, with the following objectives:

• Support Core Contributor onboarding

• Provide in-depth guidance on Core Contributor processes and tools

• Help Core Contributors easily locate role-relevant information

• Encourage effective Core Contributor participation

• Reduce reliance on community members for straightforward answers

• Strengthen the Core Contributor community overall

Where Will the Handbook Live?

The community intends to make https://docs.openedx.org the central source of truth for all community members. Therefore, it makes sense to host the Core Contributor information on this site.

What content should we add to the docs?

I audited both the Docs and Confluence content to identify Core Contributor and community-related information for inclusion on the Docs site. Based on this review, the three resources - Confluence, Docs, as well as the Core Contributor Onboarding Course - will serve distinct purposes for the community:

• Confluence:

  • Focuses on sharing ideas, documents, and collaboration

  • Serves as a space for community contributions and discussions.

• Docs:

  • Contains authoritative content, such as processes, guidelines, and project policies.

  • Acts as a self-paced reference with detailed documentation, including step-by-step instructions, best practices, FAQs and more for new contributors.

  • Updated through GitHub pull requests.

• Onboarding Course:

  • Provides a structured, interactive learning experience.

  • Includes exercises, quizzes, and videos for hands-on engagement.

  • Complements the Docs by offering a more guided, practical learning journey for new contributors.

  • Includes links to resources in the Docs, where relevant, to support the Core Contributors' learning journey.

Based on the resource purposes outlined above, I propose moving specific sections and their subsections from Confluence to the Docs. These sections and subsections will be updated as needed to provide additional information or clarification. To prevent duplication, any content moved from Confluence to the Docs will be removed from Confluence.

Here are the sections I’d like to move into the Docs from Confluence:

• https://openedx.atlassian.net/wiki/spaces/COMM/pages/941457737

• Core Contributor Program

• Engaging with the Open edX Community

• Technical Oversight Committee (TOC)

• Working Groups: Only move content related to guidelines, and link to Confluence where necessary.

• Events: Conference, Meetups, etc.: Only move content related to guidelines, and link to Confluence where necessary.

• Maintainership Sarina, could this page be combined with the existing Maintainers section in the Docs? Or has that already been done? If so, we can remove the duplicate content from Confluence to reduce context switching and decision fatigue.

With the go-ahead from community members I have archived the following in Confluence (a win!):

• Community-built features and external tools

• XBlocks Directory

• Errors encountered while setting up dev environments

• Q&A during Dev Onboarding

• Community Health Analytics

• edX Themes Directory

• Open edX Platform Services: Freelancers

• SCORM in Open edX HomeOpen edX Community

Proposed Navigation changes to Docs

TL;DR

• Rename “User Home Pages” to “Role Guides” for better clarity

• Introduce a top-level “Core Contributor Handbook” item to make it more distinct from role guides

• Keep the “Quickstarts” label but move it to the top of the nav for accessibility

• Deprecate the “Open Source Community” section and redistribute content logically

“User Home Pages” → “Role Guides”

While “User Home Pages” makes sense internally, “User” feels technical and vague for non-developers. “Home” introduces inconsistency, because we’re not appending all top-level sections with “Home.”

I propose renaming this to “Role Guides” as it’s clearer, and friendlier. It also gives us the flexibility to elevate key non-role sections (like the Core Contributor Handbook or Releases) without muddying the structure.

“Core Contributor Handbook” (New top-level nav item)

I propose adding a new top-level navigation item called “Core Contributor Handbook”. This section will serve as a central guide for all current and aspiring Core Contributors to the Open edX project. Emphasising “core” helps clarify its focus and audience.

The landing page could include an intro such as:

“A central guide for all current and aspiring Core Contributors to the Open edX project.”

Below is a suggested initial structure. This can evolve iteratively as content is moved over and refined.

• What is a Core Contributor (CC)?

• How to become a CC

• How to help the project

• What is the Product Roadmap?

• How to read the Product Roadmap

• What is a CCs Scope of Work?

• Onboarding

• Offboarding

• Contributing

• Roles and Responsibilities

• Current Core Contributors

• Community Events

• Community Communication

• Working Groups

• Technical Oversight Committee

• Pull Requests Needing Review ↗

• Open edX Proposals (OEPs) ↗

Note: Most of these documents currently live in Confluence — they should be moved to the Docs site and then archived or deleted from Confluence to reduce duplication and confusion.

“Quickstarts”

• Move “Quickstarts” to the top of the nav, just before “Role Guides,” as it’s the easiest, most accessible entry point for new/uncertain users. Placing them upfront reduces friction and decision fatigue, guiding users clearly to where they can get started immediately.

• Keep all items visible to avoid hiding useful entry points.

• Simplify and shorten titles if possible to make the items less wordy and more scannable. This is where I’d love your suggestions!

• Add a subtitle like “Common starting points for all contributors” to provide helpful context without adding clutter.

“Open Source Community”

At the moment, contributor-related resources live on Confluence, and on the Docs under a “Community” section, which appears under the “User Home Pages,” and again further down the navigation under “Open Source Community”. The use of “Community” in both headings is confusing, as both sections contain overlapping and differing content, making it unclear where contributors should go for reliable information. I suggest deprecating and redistributing content from this section.

Proposed Top-Level Navigation Layout

• Quickstarts

• Role Guides

• Core Contributor Handbook

• Open edX Releases

• Other Topics

Next steps:

1. Restructure the Docs Navigation

Update the navigation structure in docs.openedx.org as proposed:

• Rename “User Home Pages” → “Role Guides”

• Add “Core Contributor Handbook” as a new top-level item

• Move “Quickstarts” to the top of the nav

• Deprecate “Open Source Community” and reassign content

2. Move authoritative content from Confluence to the Docs

We'll begin migrating key content from Confluence to the Docs site. Once moved, the source content should be archived or removed from Confluence to avoid duplication.

Since this will be iterative and collaborative, we need a simple way to track progress.

Suggestion: A GitHub project board with columns like:

• To Do

• In Progress

• PR Open

• Done

Each task can be a page or section, with assignees and notes.

3. Define Additional Steps

We’ll scope out next priorities once navigation and migration plan are in place.