We’d like to meet with Open edX and edX engineers to align on multiple documentation efforts that are happening in parallel and to collectively hash out blocking open questions so we can make faster decisions moving forward.
Eliminate toggle_warnings → can include in the descriptions
Need to update the tooling to support paragraphs
Categories/Tags - (constrain or) live list of the values for this so categories can actually be useful.
Dynamic runtime rules checking of toggle values and their interdependencies.
Toggle Expected Default Deadlines (Proposed)
Use Case 1: Incremental Release (expected timeline: 3 months) Use Case 2: Launch Date (expected timeline: 3 months) Use Case 3: Ops - Monitored Rollout (expected timeline: 3 months) Use Case 4: Ops - Graceful Degradation (expected timeline: 5 years) Use Case 5: Beta Testing (expected timeline: 6 months) Use Case 6: VIP / White Label (expected timeline: 5 years) Use Case 7: Opt-out (expected timeline: 2 years) Use Case 8: Open edX option (expected timeline: 3 years)
(15mns) Review/Editdocumentation principles described in OEP-19 Dev Docs. Namely,
Docs should be co-located with their relevant code (eg., devstack docs recently moved out of edx-documentation).
Decision records: ADRs and OEPs
The edx-documentation repo should contain only user-facing (learner and educator) docs. All developer and operator docs should not belong here.
The edx-developer-docs repo should contain developer docs that are system-wide and orphaned.
Plugins would also have their operations and docs - we can pull those into a central location using Sphinx tools.
Docs should be searchable via Google.
Google Custom Search Engine for Open edX info: https://docs.edx.org/search
The top-level index located at edx-developer-docs.
(5mns) Review/Edit short-term objectives
Toggle/Settings initiative by Arch-BOM/edX
Discoverability of features in the system (what features exist and how to use them)
Consistency of toggles/settings when testing in multiple environments (with automated reports/alerts of inconsistent values)
Sustainable pipeline to DEPR with accountable feature deadlines (with automated reports/alerts of expired toggles)
Documentation initiative by Build-Test-Release working group
Improve the onboarding experience of new Open edX operators
Improve experiences of upgrading and managing Open edX instances
Multi-tenancy requirements: allow toggle enablement for different sites
(45mns) Answer Questions (some can happen via discourse)
What information to include in toggle annotations? See example.
In using Sphinx to generate docs for Django settings, how will this interact with the automated docs generated by their annotations?
edx-platform dependencies and other IDAs will need to work with Sphinx. It takes effort to maintain and keep working and updated.
Sphinx needs to import the modules to generate the docs. For edx-platform, Sphinx needs to import all 300+ dependencies, etc.
Alternatively, having a tool that extracts the docs/annotations - and then have Sphinx run over a smaller set.
REST API and Python APIs
For Python APIs - if we do the doc generation for a subset of the apps, this can scale.
Proposal (pending discussion with @Régis Behmo): Update the PII annotations tool to support unstructured text in order to meet BTR requirements.
What is the final output of edx-platform’s documentation generation?
Would it include a mix of outputs from API annotations, settings, guides, etc?
How will we include annotations from Django App Plugins?
Proposal: Use Sphynx for the organization of the documentation; discoverability within the repo as well as a central location.
What is the purpose of the FEATURES Django settings dict? For simplification, shall we remove this dict (via the DEPR process)? See discourse thread.
Would it make sense to merge the edx-documentation and edx-developer-docs repositories? There are multiple entry points for Open edX documentation. Shouldn’t we try to generate all docs (developer, edx-platform, ecommerce…) in a single folder such that they are all accessible at a single URL?