Documentation of Toggles/Settings/etc - 2020-03-20

Owned by Nimisha Asthagiri (Deactivated)
Last updated: Apr 10, 2020
3 min read

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.

Meeting Recording

https://drive.google.com/open?id=1WyTjLy6CrKCG85DtONDTyuFVra4AFftR

Open Questions

  • Combining decentralized docs from plugins and individual features/repos into a coherent central documentation?

    • Is edx-developer-docs just a top-level index or also pull in docs centrally as well?

  • How are we going to backfill all the documentation? - Organizing the resourcing effort

Notes

  • Toggle durations that are less than Named Release timelines would impact the community less since they are only tracking named releases.

  • Toggle Annotations

    • When toggles are interdependent, how can we capture this?

      • Can we codify toggle hierarchy via toggle namespaces?

      • Ideas:

        • Put in warnings for now.

        • Present a concrete example and we can see how to address it.

        • Codify toggle hierarchy (namespaces, waffle enhancements, etc)

      • Actions:

        • 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.

  • Ideas:

    • 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)

Agenda

  • (15mns) Review/Edit documentation principles described in OEP-19 Dev Docs. Namely,

    • Location

      • 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.

      • Notes:

        • Plugins would also have their operations and docs - we can pull those into a central location using Sphinx tools.

    • Discovery

      • 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

      1. Discoverability of features in the system (what features exist and how to use them)

      2. Consistency of toggles/settings when testing in multiple environments (with automated reports/alerts of inconsistent values)

      3. Sustainable pipeline to DEPR with accountable feature deadlines (with automated reports/alerts of expired toggles)

    • Documentation initiative by Build-Test-Release working group

      1. Improve the onboarding experience of new Open edX operators

      2. Improve experiences of upgrading and managing Open edX instances

    • EduNext Priorities

      1. Discoverability

      2. Pluggability

      3. Multi-tenancy requirements: allow toggle enablement for different sites

  • (45mns) Answer Questions (some can happen via discourse)

    1. What information to include in toggle annotations? See example.

    2. In using Sphinx to generate docs for Django settings, how will this interact with the automated docs generated by their annotations?

      1. See @Régis Behmo's PR.

      2. See Sphinx Plugin notes in OEP-30.

      3. Notes:

        1. edx-platform dependencies and other IDAs will need to work with Sphinx. It takes effort to maintain and keep working and updated.

        2. Sphinx needs to import the modules to generate the docs. For edx-platform, Sphinx needs to import all 300+ dependencies, etc.

        3. Alternatively, having a tool that extracts the docs/annotations - and then have Sphinx run over a smaller set.

        4. REST API and Python APIs

          1. For Python APIs - if we do the doc generation for a subset of the apps, this can scale.

        5. Proposal (pending discussion with @Régis Behmo): Update the PII annotations tool to support unstructured text in order to meet BTR requirements.

    3. What is the final output of edx-platform’s documentation generation?

      1. Would it include a mix of outputs from API annotations, settings, guides, etc?

      2. How will we include annotations from Django App Plugins?

      3. Notes:

        1. Proposal: Use Sphynx for the organization of the documentation; discoverability within the repo as well as a central location.

    4. What is the purpose of the FEATURES Django settings dict? For simplification, shall we remove this dict (via the DEPR process)? See discourse thread.

    5. 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?