Open edX Handbook

Owned by Cassie Zamparini
Last updated: Oct 31, 2024
5 min read

Proposal by @Cassie Zamparini on behalf of OpenCraft

Topic

Indicate which topic your proposal falls under:

Enhance Core Contributor Onboarding
Improve Collaboration, Communication & Reporting
Improve Fulfilling Commitments and Planning Processes
Improve Review Processes

Overview

The recent survey highlights a clear need for a better resource that details the processes and roles associated with onboarding and the ongoing responsibilities of Core Contributors. To address this, I propose the creation of a dynamic, comprehensive and easy-to-navigate "Open edX Handbook" that will be continuously updated and refined to meet the community’s evolving needs.

Initially, the handbook will involve relocating and consolidating existing Core Contributor information and expanding the information in a newly established space (eg. Similar to Open edX docs or the The OpenCraft Handbook). Over time, this space will evolve into a centralized, all-encompassing resource designed to enhance documentation accessibility, clarify information, and reduce information overload for the entire Open edX community, not just Core Contributors.

The primary goals of the first phase of this initiative are Core Contributor focused:

  1. Support the Core Contributor onboarding process

  2. Provide more in-depth guidance on Core Contributor processes and tooling

  3. Help Core Contributors easily locate information relevant to their roles

  4. Promote effective Core Contributor participation

  5. Reduce reliance on community members for straightforward answers

  6. Strengthen the Core Contributor community as a whole

Survey Results

Here are some key results from the survey that supports this initiative:

  • 32% of the community rated onboarding experience as lacking, also citing content as too high-level. A handbook can support the onboarding course, consolidate and clarify information, and reduce overwhelm.

  • 71.5% of the community have a limited understanding of Core Contributor Sprint Processes. Clear process documentation in a handbook can improve comprehension.

  • 78.9% of the community want fewer communication tools. Contributors face low engagement on Slack and challenges with too many channels. Comprehensive guidelines for asynchronous communication could enhance engagement.

  • 77.1% of the community would like more collaboration. Concerns include coordination issues and unequal engagement rights. The handbook can offer best practices to improve teamwork.

  • 68.5% of the community struggle getting reviews. Contributors find it hard to locate PRs and receive timely feedback. The handbook can clarify review expectations and procedures.

  • 65.7% of the community would like better planning of Core Contributor work. Including planning strategies in the handbook could boost productivity and help CCs better reach their commitments.

Solution

To address the challenges outlined in "Enhancing the Core Contributor Experience," I propose the following solutions to benefit both newcomers and the broader Core Contributor community:

Centralized Documentation:

  • Perform a thorough audit of existing Core Contributor documentation and consolidate it into a well-organized central repository. This will address the current challenge of overwhelming and dispersed information. Additionally, ensure to review other projects related to the Documentation (ie. Working Group information) to identify potential overlaps or opportunities for collaboration. This effort should be done in collaboration with those maintaining the core contributor onboarding course.

Enhanced Content Order and Quality:

  • Improve clarity, engagement, and informativeness of the content. Ensure accessibility for both technical and non-technical users. Implement a search, structured table of contents, cross-referenced links, and a logical content arrangement to facilitate easy navigation. Address issues of scattered information that complicate access for new Core Contributors.

Identify Content Requirements:

  • Define the New Handbook Structure

    • Based on survey feedback and existing Core Contributor information, outline the sections of the Handbook that can be developed progressively.

    • Key Information to Include based on the Survey Feedback:

      • Define abbreviations and terms (e.g. CC, OEX, TOC, OEP, ADR).

      • Clearly articulate the Core Contributor’s purpose, vision, and mission.

      • Outline actionable steps for involvement, including role-specific links.

      • Structure content based on roles, similar to GitLab’s role-based handbook model.

      • Define responsibilities for various Core Contributor roles.

      • Provide guidelines for assessing commitments to ensure accountability.

      • Offer guidelines for effective use of communication tools as proposed by Ali Hugo.

      • Include the contact details of a specific representative for role-specific guidance.

      • Detail the sprint process and outline expectations for each Core Contributor, including check-ins if necessary.

      • List all active working groups with links to their collaborative spaces.

      • Decide which information to include directly in the handbook and which to reference through links (e.g., Product Review Process, Product Proposals).

Easy Submission of Changes:

  • Host the handbook in a GitHub repository to facilitate easy submission of changes through formal pull requests. This will allow others to review and approve changes before they are implemented in the Wiki, or similar.

Add Handbook Link to Core Contributor Onboarding Course:

  • Ensure the handbook is linked in the Core Contributor onboarding course for easy access and reference. Encourage CCs to submit issues or pull requests against the handbook if they find any outdated information.

Impact

To measure the effectiveness of the handbook, we could use the following metrics:

  1. Use built-in analytics to monitor the number of views and interactions with the handbook. Confirm if current tools already capture this data.

  2. Send a brief, automated survey to new Core Contributors shortly after onboarding to gather quick feedback on clarity and usefulness.

  3. Monitor the number of support requests Axim receives related Core Contributor responsibilities. Confirm if current tools already capture this data.

By focusing on these metrics, we can quickly assess the handbook’s impact and make necessary adjustments without requiring extensive time or resources.

Timeline

I propose an iterative approach to this project. To ensure a faster process, I will assemble a team of collaborators and reviewers. This will facilitate faster content creation and timely feedback.

Phase 1: Define the New Handbook Structure (2 weeks)

  1. Define Sections @Cassie Zamparini and one additional person (TBD)

    • Analyze survey feedback and existing Core Contributor information to outline the essential sections of the Handbook.

  2. Initial Input Gathering: @Cassie Zamparini and multiple volunteers (TBD)

    • Validate the proposed list of sections with reviewers, and establish the priority order for section development.

Phase 2: Iterative Content Development and Population (Developed in 4-week intervals)

  1. Section-by-Section Development: @Cassie Zamparini and multiple volunteers (TBD)

    • Weeks 1-2: Develop content for the highest-priority sections with the help of Core Contributor volunteers.

    • Weeks 3-4: Review and refine these sections based on feedback and publish the content.

  2. Repeat Development Cycles:

    • Continue developing and refining additional sections in 4-week intervals, incorporating feedback and making iterative improvements as needed.

This structure provides a clear foundation and progression for developing the Handbook, ensuring that each phase builds effectively on the previous one.

This approach ensures a structured yet flexible development process, allowing for continuous refinement based on feedback and evolving needs.

Example Handbooks

Conclusion

By implementing this proposal, I aim to significantly enhance the onboarding experience for new Core Contributors, streamline their integration into the community, and boost the overall effectiveness and satisfaction of our current contributors. The comprehensive handbook will be a vital resource, supporting the growth and success of our community by including sections for frequently asked questions and troubleshooting. This will empower contributors to find answers independently, fostering increased self-reliance and reducing the need for community support for basic queries.