Help document the Open edX platform in celebration of International Day of Education (Jan 24)!

Help document the Open edX platform in celebration of International Day of Education (Jan 24)!

UPDATE: Doc-a-thon results available in our blog post.

This page is about the Doc-a-thon on Toggles and Settings, taking place January 25-29, 2021, and extended through March 15.

Participation will take a couple of hours to help research and document some of our feature toggles or settings.

Why Document Toggles and Settings?

The documentation for toggles and settings is a crucial source of information for a very wide audience, including platform administrators, product owners and developers.

Additionally, we can help reduce the complexity of our system by properly documenting which toggles and settings were meant to be temporary, along with target removal dates (as detailed later), to help drive deprecation/removal.


Asking for Help

There is a dedicated Open edX Slack channel #doc-a-thon.


Process for PR Authors


Feel free to add comments with questions or ask in Slack. Thank you!

Feel free to add comments with questions or ask in Slack. Thank you!

1. Read How-Tos

Get familiar with the type of documentation we will be writing, which uses annotations.

2. Sign up

Choosing a setting or toggle in the LMS Sign-up for Toggle and Settings Doc-a-thon spreadsheet:

3. Research

Research the toggle or setting to prepare for your documentation.

4. Write the annotation

Please try to annotate a single toggle or setting in each PR, or a group of related toggles and settings. See “Create your PR” for more details.

See the “Read How-tos” section above for instructions on how to document toggles and settings.

5. Create your PR

As noted above, please try to annotate a single toggle or setting in each PR, unless there is a group of related settings and toggles. The simpler the PR, the easier it will be to approve and merge.

6. Congratulations!

Thank you for documenting one of our toggles or settings! If you want to put your new skills to good use, sign-up for another one and start again.

Process for PR Reviewers

In addition to following the standard PR review process, see the following special considerations:


Where can I see the toggle and settings documentation?

Where can I see linting results?

Note: Additional linting is still in progress. You may need to rebase your PR to pick up additional linting.

You can see toggle annotation errors by searching the quality pylint errors for type “toggle” or “setting”.

Can I add a new toggle or setting, or should I only document what is on the list?

Sure, you can add new ones. Reach out to Robert Raposa to add new toggles to the sheet. You can ping in the #doc-a-thon Slack channel.

Should I document something I am an expert in or on can I pick something I am not familiar with?

You can pick anything you are interested in, whether you are an expert or not. If you are not an expert, feel free to ask on Slack. 

Are there PR reviewers assigned?

If you are a core contributor and can review, please do so. Also, anyone is welcome to help do a first-pass review. Robert will work on finding reviewers to get the rest of the PRs merged.

If flag is planned to be removed, should I remove it?

For now, please annotate that it is slated for removal/deprecation in the annotation as detailed in the how-to document. We can later follow the full DEPR process.

How do I document a setting or toggle that can be configured independently for both, LMS and CMS service variants? do I have to duplicate the annotations in both env files?

See instructions for the same toggle in different services.



  1. Communications

    1. Announced earlier at contributors meeting

    2. Announced in discourse - including banner!

    3. Announced in slack

    4. Separate slack channel was great!

  2. This document was very useful in getting started. Regis’s video was also nice to get started, having the full process recorded would be really nice.

  3. Spreadsheet to self-serve for signups and add notes.

  4. Opening and closing ceremonies!

    1. With Metrics!


  1. Perfect is the enemy of good?

    1. What could have sped up the PR reviews?

      1. (Future) Toggle linting and lint amnesty will provide faster feedback loops.

      2. We were resolving open questions while reviewing.

      3. Splitting delegation and reviewing to different people.

  2. Extend the event to a longer duration!

    1. What are the bottlenecks?

    2. Longer time → How to keep the energy up?

      1. Have a goal!

  3. Badges and “competition” helps encourage

    1. Would prefer to externalize outside of Discourse.

    2. Top contributor award as well

Future Notes

  1. edX Legal team needs to be given heads up about the doc-a-thon. If many new authors participate, signing a new contributor agreement and Legal processing them can become a bottleneck. Also, need this agreement in Docusign!