Below is the list of tasks that need to be accomplished before we can begin accepting contributions to this repo from anyone in the community. Once these tasks are done we can announce more widely that the repo is ready to accept contributions.

• #18
• #19
• Publish this repo to https://docs.openedx.org and keep in sync with master.
• Setup the repo to take contributions
  • Ensure the CLA check is setup and running.
  • Require successfull doc builds before merging PRs
  • Require PRs for changes to main branch.
  • Add an openedx.yml

A Reference Doc that details and defines all of the complex problem types that are possible on the OEX platform. Includes templates and examples of how they have been implemented on current instances. To inspire and get more users familiar with what's possible.

• #141
• #142

Write this document

Relevant URL: sample text question answer
Reporter Role(s): Educator
sample text question answer

Contact Name: sample text question answer

This issue was generated from the feedback form on docs.openedx.org.
If you need the contact's e-mail address, it may be found in the original form. Ask a docs maintainer for access.

Write a Quick Start doc for course operators covering the basic, necessary steps to get a course up and running in ~under 20 minutes.

Quick Start Template you can use as reference/inspiration: https://docs.openedx.org/en/latest/educators/quick_starts/build_a_course.html

• #131
• #172

Write this document
Andres, Feanil
https://discuss.openedx.org/t/staff-admin-member-by-organization/7345/12?u=dave

The Problem:

Right now the doc default url is https://docs.openedx.org/en/latest/* this would default en lang. However when changing the langauge using transifex selector lang it would change the cotent to the selected langauge, however the url would always contain en. This has the following downside:

• The url is not semantic and is incorrect (in case user picked a different lang than en)
• There isn't a mechanism to generate links for different lang code to force the docs site show content in a spesfic language.

Suggested Solutions

The good news is TX could view translated content if code exits in url; as per doc it can detect lang code in path i.e. /ar/ or in query params i.e ?lang=ar. However for this to work, from TX side we need enable lang detect which is a simple configuration can be added in this context :

<script type="text/javascript">
    window.liveSettings = {
        api_key: "7af91b0a80054fab9de5fad172a25171",
         detectlang: true // This option can also be a function which should return the lang-code refer to refs below
    };

From readthedocs prespective (I am speculating here), to allow such featuer integration to work as expected, we would probably need to choose from the following options:

• Remove /en/ part of the url (so then if we want to link a spesfic lang of the doc: we would just add ?lang=lang_code in the end of the url.
• Allow readthedocs for whatever lang code exits in url to just serve the default page. i.e.
  • For url https://docs.openedx.org/en/latest/* TX JS wouldn't do anything
  • For url https://docs.openedx.org/ar/latest/*TX JS would mutate the DOM and show arabic version.

For second option above; since TX works in JS level (it mutate the dom content), it doesn't matter if Readthedocs would always serve english version for whatever code exits in the url. The caveate for this apporach is SEO, however SEO bots/indexer do run JS code , but of course to ensure we get the right langauge is being index we could consider prerender the site in different langauges (see ref 3), but then that might require more complex readthedocs configuration/integration. Although I don't know how important SEO is for doc site, I can nonetheless recommand if SEO is imporant for whichever approach we choose, someone would need to register the domain docs.openedx.org in Google search console so that we are confident content per langague are correrctly indexed.

How would this relate to bigger project:

Once this is resolved, in the context where the platform direct to extenral documenation source, we could direct learner/course author to the correct version of the doc that matches their language in account settings. Instead to just have hardcoded link to English.

I think this topic was once raised in TWG, to ensure the platform offers a consistent i18n experience. One blocker at that time was that docs is only available in en, but since its available in multiple lang and assuming this issue would be resolved. Then the last requirment to allow such expirence should be trivial or at least. We would need to ensure first for whatever external help url used, it should have a page/resource exits in this project and developer would be asked to add lang_code in the url.

Refs:

1. https://docs.transifex.com/live/webmasters
2. https://docs.transifex.com/live/api
3. https://docs.transifex.com/live/seo-guide#javascript-and-seo-concerns

The old translators documentation lives here: https://edx.readthedocs.io/projects/edx-developer-guide/en/latest/internationalization/i18n_translators_guide.html

This is out of date and the translation working group has created a new guide for translators: https://docs.google.com/document/d/1XwkGelCcBgJsYx02y7Ck6_Uk9CU9EHUf5-EZQD0autU/edit#

This is a copy of the new guide, that Brian and I have been editing as we prep for it to go into the new docs site: https://docs.google.com/document/d/1gWURNk_UflHkSZK7LwRWYOx2fcyVhX9PuMG2pc-dbmc/edit#

Remove the old guide from the old docs site and point it to the new one which should converted to RST and moved to docs.openedx.org

Can we outline what the new structure looks like and then have someone on the translations working group actually write up the new doc?

Specific Docs to Write

• Translators Reference: HTML
• Concepts: Translating HTML
• Howto: Request a new language
• Howto: Join a translation team? This is kind of included in the quickstart
• Howto: Join a review team
• Concepts: Placeholders
• Translators Reference: Placeholders

Write a Quick Start doc for site operators covering the basic, necessary steps to set up a course in ~under 20 minutes.

Quick Start Template you can use as reference/inspiration: https://docs.openedx.org/en/latest/educators/quick_starts/build_a_course.html

Write this document

What are the most important “how tos” needed for Developers? Goal to create a canonical list/outline that can be populated later (David Joy - overlap with backend and front end dev quickstart)

• Start a shared Sheets with interested contributors to begin collecting article title ideas

Write a Quick Start doc for plugin developers covering the basic, necessary steps to get started with developing plugins/set up a plugin dev environment in ~under 20 minutes.

What is a Quick Start? https://documentation.divio.com/tutorials/

Quick Start Template you can use as reference/inspiration: https://docs.openedx.org/en/latest/educators/quick_starts/build_a_course.html

Currently the requirements.txt file is just copied over from a different repo and not actually generated with pip tools. Update the repo so that it follows the same pip standard as the rest of our repos.

AC:

• make upgrade work.
• make upgrade is automatically run on a regular cadance.
• All requirements in requirements.txt are pinned.

Updated list: https://docs.google.com/spreadsheets/d/1m1zTyiIDYkDI79AgGw_JNeWi1hkIZptRUbwirgPnPJQ/edit#gid=1843368591

Write this document
Bernard Badzioch, Jenna

Relevant URL: sample text question answer
Reporter Role(s): Educator
sample text question answer

Contact Name: sample text question answer

• This issue was generated from the feedback form on docs.openedx.org.
• If you need the contact's e-mail address, it may be found in the original form. Ask a docs maintainer for access.

Write this document

What are the most important “how tos” needed for Educators? Goal to create a canonical list/outline that can be populated later
Dean, Jenna
https://docs.google.com/spreadsheets/d/1m1zTyiIDYkDI79AgGw_JNeWi1hkIZptRUbwirgPnPJQ/edit#gid=0

• #129
• #130
• Circulate the how to table of contents as a google sheet to those interested in educator contributions
• Create a how-to article issue for each for the "to write backlog"

The Quick Start for Educators covering the basic, necessary steps to build a course is created. It is open for review, feedback during this beta phase of the Open edX documentation upgrades.

Doc link: https://docs.openedx.org/en/latest/educators/quick_starts/build_a_course.html

• #128
• #171

Write this document

As a writer, I want a way to be reminded of pages that I should revisit after some time period.

eg. This doc will become out of date in 6 months, remind me to check back in on it then.

Write this document
How To: (select 2-3 for educator or operator)
Hildy, Jenna

Write a Quick Start doc for software developers covering the basic, necessary steps to get started with customizing the platform in ~under 20 minutes.

What is a Quick Start? https://documentation.divio.com/tutorials/

Quick Start Template you can use as reference/inspiration: https://docs.openedx.org/en/latest/educators/quick_starts/build_a_course.html

The discovery/proposal doc around open edx documentation seems to be generally getting positive feedback. Given this feedback, codify the proposal for the open edx community as an OEP.

AC:

• OEP reviewed and accepted at least as provisional.

What services/MFEs are there? What do they do? What is their current state?

Relevant URL: sample text question answer
Reporter Role(s): Educator
Contact Name: sample text question answer

sample text question answer

• This issue was generated from the feedback form on docs.openedx.org.
• If you need the contact's e-mail address, it may be found in the original form. Ask a docs maintainer for access.

Write a Quick Start doc for software developers covering the basic, necessary steps to get started with customizing the platform in ~under 20 minutes.

What is a Quick Start? https://documentation.divio.com/tutorials/

Quick Start Template you can use as reference/inspiration: https://docs.openedx.org/en/latest/educators/quick_starts/build_a_course.html

As an open edX operator, I'd like a reliable source of information about toggles and settings that apply to the named release that I am deploying.

As the release notes writer, I'd like an easy way to be able to diff releases of the technical reference, so I can quickly build lists of new and removed settings for the release notes.

@pdpinch, Read The Docs allows setting multiple versions that are built. We could even add public versions for tagged releases. This way, users will be able to switch between them with the panel in the bottom right corner of the page. Example page, RTD config:

Originally posted by @Agrendalath in openedx/wg-build-test-release#133 (comment)

Developer content may come from docs that live in the relevant repo. Update the reference space so that you can easily navigate to documentation for repos that are a part of the Open edX platform.

• Do this work ourselves on 2-3 pilot repos.
• Use that to write how-tos that can be used by maintainers to do this work on their own repos.
• Ask the maintainers to do this work in repos they maintain, give them a quarter or two to complete it.

Ex
Quickstart: Build a course
Quickstart: Operate a course

Remove persona duplications and inconsistencies

If it's an empty page, make sure there is a ticket for it and then remove the empty page.

Figure out the correct license for this repo and add it.

Creative commons might make sense since it's mostly text content and not code. Talk to tCRIL legal before deciding.

docs.openedx.org has a google form on it that people can use to provide feedback even if they don't have github accounts. Currently that form is in @markH-Docemus google account. We should move it to the tCRIL account and operationalize it.

Acceptance Criteria

• Feedback form lives in a tCRIL shared google drive.
• Docs team, in particular @feanil @jmakowski1123 and @markH-Docemus have access to it.
• Setup some something to make sure the feedback response are reviewed regularly.
  • Maybe a calendar reminders to review this form
  • or some other automation to make github issues from the form responses as they come in.

In Quickstart: First Open edX Pull Request:

"macOS" is a stated assumption, even though nearly all of the steps would work on Linux. There are only a couple references (Homebrew, Docker for Mac) that need to be updated for Linux compatibility. Many potential Open edX devs are Linux users.

Additional suggestion: Have a tabbed section, where each tab is an OS, for OS-specific instructions. Such a control could also be used to organize the Intel vs ARM64 instructions.

What are the most important “Common concepts”: Educators/Instructional Designers
Shannon, Jenna

• #173

The open edx project has a cookie policy: https://openedx.org/cookie-policy/

This policy must be linked from the footer of the docs site to ensure we're in compliance of various laws.

What are the most important “how tos” needed for Course Operators? Goal to create a canonical list/outline that can be populated later

The automated make upgrade script has failed the last 3 times it has run. Look into why and fix the issue.

Ideally we would also be able to enable auto merging on make upgrade PRs.

Relevant URL: https://docs.openedx.org/en/latest/other/feedback.html
Reporter Role(s): Site Operations
Contact Name: Feanil

I'm testing to make sure all the form wiring works as expected.

• This issue was generated from the feedback form on docs.openedx.org.
• If you need the contact's e-mail address, it may be found in the original form. Ask a docs maintainer for access.

What are the most important “how tos” needed for Site Operators? Goal to create a canonical list/outline that can be populated later