Discovery Proposal: Define and recommend an approach for organizing docs.openedx.org

[jmakowski1123]

As Discovery work for this Initiative's first two milestones is completed (https://github.com/openedx/tcril-engineering/issues/103, https://github.com/openedx/tcril-engineering/issues/104), we can begin to scope/groom this epic.

Approach:

We have identified the need for a central Documentation Tree/Documentation index that aggregates and points to the places across the Open edX ecosystem where documents live. A comprehensive listing of all Open edX documentation was generated in the Documentation audit: https://github.com/openedx/tcril-engineering/issues/104. At this stage, we will explore creating a docs.openedx.org space where the Documentation index exists.

Drawing on persona data compiled in https://github.com/openedx/tcril-engineering/issues/103, we will create a set of recommendations for each persona that is grounded in a "user story" approach to defining the documentation needs and user journey through the documentation architecture.

The targeted outcome is a Discovery Artifact in the form of a proposal with a visual "show and tell" with recommendations based on our discovery work that we can circulate to the community for feedback.

Child tasks for this epic are evolving:

"Inform" tasks:

• [x] #177
• [x] #215
• [x] #184

"Action" tasks:

• [x] #176
• [x] #229
• [x] #178
• [x] #228
• [x] #230

---

Notes from Initial conversation, 1/10/22 Discovery to define the best approach for defining the architecture/information hierarchy for docs.openedx.org, orienting toward end goals, appropriate persona, and sustainability.

Notes from various conversation:

• Audience: There will be many different audiences, the front page should clearly help each audience get to the home page for what they need.
  • See https://codex.wordpress.org/ and https://docs.github.com for some examples of how we might organize this.
• Stubbing out a top-down hierarchy of content will probably allow us to manage the information better and make the documentation more coherent and approachable.
• We need to think about making the process of keeping the documentation up-to-date sustainable, how do we do that? What processes should we be changing, is there value in a docs working group to regularly think about this problem?

[ormsbee]

@feanil, @jmakowski1123: Does it make sense for me to try to pick up some part of this next, or are we waiting on our expected contractor?

[feanil]

@ormsbee I think having something from you that we can have as a starting point for Mark to look at would be useful and maybe we can hand this ticket to Mark after he arrives.

[jmakowski1123]

@feanil @ormsbee I want to flag that we have a few related tickets open under the broader "documentation" project. I might add to the next planning meeting to discuss streamlining them, esp as some may be epics under the larger initiative umbrella. I've listed what I think are all related tix here: https://github.com/openedx/tcril-engineering/issues/89 (and I see #89 as the possible Initiative umbrella)

[jmakowski1123]

Contingent on completing #103 and #104

[jmakowski1123]

Brainstorming notes from Documentation Kickoff Meeting (Mark, Feanil, Jenna, 2/14/22):

• docs.openedx.org to serve as a linktree/index for all documentation pointing to places where relevant docs live
• one key is to separate "how to" docs from "explainer" docs
• focus persona interviews and first pass at docs at building a plain vanilla course
• scale organization strategy to seamlessly enable providers to enrich/modify/cater core plain vanilla docs to meet their specific needs

Post persona profile work #103 and audit #104 , next epics might include:

• build skeleton templates by persona - what must be included, what format/modality (model for core vs extended)
• specific personas may include - component skeleton for xblocks (dev), new dev/onboarding (dev)
• versioning work