[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.

Since the 'Handbook' content will be hosted on the Docs site, we need to find a way to integrate it seamlessly within the existing navigation:

Open

Existing navigation

What content should we add to the docs?

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

• Wiki:

  • 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 the Wiki 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 the Wiki to the Docs will be removed from the Wiki.

Here are the sections I propose moving:

• How to Start Contributing Code: This is already linked to from the Docs. I think we should remove it from the Wiki and rather house it on the Docs.

• Core Contributor Program

• Engaging with the Open edX Community

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

• Maintainership

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

• Technical Oversight Committee (TOC)

Proposed Navigation changes to Docs

Updating Docs

Open

To maintain consistency, I suggest applying the Documentation Layout to both the Core Contributor and Maintainership sections. Below, I’ve outlined the proposed navigation in more detail with links to the relevant existing content:

Core Contributors:

Community Communication

• Discuss this with @Ali Hugo when work is completed on this proposal

Working Groups

• Introduce the Working Group concept and link to the Wiki accordingly

Technical Oversight Committee

• Overview

• Charter of the TOC

• Charter of the TOC Community Elections

Open edX Proposals (OEPs) ↗