Open edX Handbook

[cassiezamparini]

Proposal

See proposal

Phase 1 Schedule

1: Define the New Handbook Structure

• Assignees: @cassiezamparini and @jalondonot
• Task: Analyze survey feedback and existing Core Contributor information to outline the essential sections of the Handbook.
• Timeline: 13 - 24 January 2025

2: Get Feedback on New Handbook Structure

• Assignees: @cassiezamparini, @jalondonot and wider community.
• Task: Validate the proposed list of sections with reviewers, and establish the priority order for section development.
• Timeline: 27 January - 9 February 2025

3: Incorporate Feedback into the New Handbook Structure

• Assignees: @cassiezamparini
• Timeline: 10 - 14 February 2025

4: Create a Space for the Handbook in the Open edX Docs

• Assignees: @cassiezamparini and TBD
• Tasks:
  • Set Up a GitHub Repository for Handbook for facilitating easy submission of changes. (See how this page in the "Docs" explains how to update documentation. This is a nice resource to include)
  • Create a section in the Open edX docs.
• Timeline: TBD

Phase 2 Schedule

The phase 2 timelines will be fleshed out once Phase 1 is completed.

1: Iterative Content Development and Population

• Developed in 4-week intervals
  • 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.

[antoviaque]

@cassiezamparini During the last meeting of the coordination working group, we set as a goal to have a plan for each of the approved proposals from the summit. It's likely going to be tricky to get things done with Christmas, but what would be your plan & timeline beyond that?

[cassiezamparini]

@antoviaque I will only be able to start tackling this in January 2025. My aim is to post a plan then :)

[cassiezamparini]

@antoviaque and @jalondonot I've added a schedule at the top of this page.

---

@openedx/ccp-committer-jswope00 One thing I will need technical help with is this item:

Create a Space for the Handbook in the Open edX Docs

Tasks:

1. Set Up a GitHub Repository for Handbook for facilitating easy submission of changes or will we leverage the Docs repository? See my note below though on having a project board dedicated to the Handbook.
2. Create a Handbook section in the Open edX docs

Would you be able to assist me? Or suggest someone else that could help?

---

Since the Handbook will / might have its own repository, it can also have its own project board. This will allow us to manage multiple content creation tasks concurrently.

I know we agreed to use the CC Topics board for all Summit tasks @antoviaque, but I think the Handbook is a different case, as it will be an ongoing project. So that's why I’d prefer to manage the Handbook content tasks on their own board.

@openedx/ccp-committer-jswope00, how do you currently manage the Docs tasks?

[antoviaque]

@cassiezamparini Thanks! The timeline looks good 👍

I know we agreed to use the CC Topics board for all Summit tasks @antoviaque, but I think the Handbook is a different case, as it will be an ongoing project. So that's why I’d prefer to manage the Handbook content tasks on their own board.

No worries at all - we can organize the boards as is the most convenient, especially for the people who will be using them the most, ie likely you :)

[cassiezamparini]

Thanks @antoviaque

@sarina @feanil @mphilbrick211 Let me know if you have any thoughts on the below from an Axim perspective:

---

One thing I will need technical help with is this item: Creating a Space for the Handbook in the Open edX Docs which will mean setting up a GitHub Repository for Handbook for facilitating easy submission of changes / leveraging the current Docs repository? I'd love everyone's thoughts on this and any colunteers to help (I've pinged @openedx/ccp-committer-jswope00 too).

Ideally I'd also like the Handbook to have it's own project board to handle the content creation aspect.

@antoviaque Feel free to add any comments about this too...

[sarina]

We'd prefer to not create new repositories if possible. Would it work to create space on docs.openedx.org?

[cassiezamparini]

@sarina I'm happy with that. As long as it's cool if the Handbook has it's own project board?

Who would be best to help me set it up / get the lay of the repository land (this is new territory for me!)? Alternatively I can ask one of our in-house CC's to assist?

[sarina]

I would add the handbook to the Community section of the docs, https://github.com/openedx/docs.openedx.org/tree/main/source/community For all GitHub requests (boards, permissions, repos, etc), you can go ahead and make an Axim Engineering ticket.

…

On Thu, Jan 9, 2025 at 4:01 AM Cassie Zamparini ***@***.***> wrote: @sarina <https://github.com/sarina> I'm happy with that. As long as it's cool if the Handbook has it's own project board? Who would be best to help me set it up / get the lay of the repository land (this is new territory for me!)? Alternatively I can ask one of our in-house CC's to assist? — Reply to this email directly, view it on GitHub <#128 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAPEWJPRGET2V6BZ76ZWGHT2JY3HFAVCNFSM6AAAAABQBOXQWSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNZZGUYDINRWG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[cassiezamparini]

I've completed round 1 of the proposed Handbook structure. I'll be presenting it at the Contributor Coordination Working Group today for anyone who wants to understand my thinking before commenting below.

• Proposed Structure Discovery Document
• Structure Mockup in Figma

cc. @jalondonot @antoviaque

[MaferMazu]

I don't have access to the discovery document. But from the Figma, my comment so far is to focus only on the handbook document or section. I understand you found some improvements to the documentation structure; we can open another conversation around that 🙌, but for really having progress on this, I suggest limiting the scope, thinking about what we want to add to the handbook, and if there is some information already in the doc, we can redirect to that information.

Thanks again for this work, @cassiezamparini ✨

[sarina]

@cassiezamparini could you put the discovery document in the wiki (where discoverability/searchability/sharability is easier)?

[jswope00]

@cassiezamparini glad that we are able to incoporate this into docs.openedx.org, so that will serve as the central source of truth and we can more easily prevent duplication and maintain the handbook.

What I take away from the mockup is that there is a lot of real estate dedicated to the specifics of core-contributorship. I suggest that we want docs.openedx.org to be an entry point for many kinds of users, and each user should feel welcome and that they are in the "right place" for them. These many details about core contributors detracts from that. But I'd also need to see the whole proposal before giving more feedback than that. I think there is a way to highlight this important handbook while keeping the rest of the docs home approachable for all.

[cassiezamparini]

@jswope00 I appreciate your feedback! I presented this in the CC WG yesterday so if you're keen to watch the discussion here it is.

I'm going to be reworking my proposal quite significantly after the feedback, focusing on smaller changes for now, rather than overhauling the navigation's UX.

When auditing the Docs and the Wiki for my proposal I found the overall navigations of both quite difficult to follow. However I realise I need to propose smaller changes and things will incrementally improve from a UX standpoint. Once I rework the doc I'll ping you for your feedback. I'd also like the Docs Working group to review it before changes start being implemented.

[cassiezamparini]

@jswope00 @MaferMazu @antoviaque @jalondonot I'd appreciate your feedback on my updated Discovery 😄

[antoviaque]

@cassiezamparini Sure! Can I ask you to create a review task in my upcoming sprint? :)

[jalondonot]

Absolutely, @cassiezamparini! I'll find some time next week. Do you have a deadline in mind for this?

[cassiezamparini]

@jalondonot It would be great to have your feedback by next week if possible? @MaferMazu yours too if also possible? 😄