FYI this has been discussed during the last contributors meetup - here is the summary of the discussions:
Identified Concerns and Suggestions
@pdpinch raised concerns about the lack of documentation for waffle flags, specifically in the context of the edX implementation. He explained that there was variability in how waffle flags were implemented and a lack of clarity about the decision-making process behind these implementations. @Felipe suggested that contributors could help by reporting and addressing issues with the implementation of features.
Emphasis on Clear Documentation
@Felipe emphasized the importance of clear documentation for waffle flags and the need for a well-defined process for contributors to follow. He mentioned that if a decision was made for a specific reason, it should be documented to avoid confusion.
@jalondonot asked for suggestions on how to further discuss and improve the documentation. Jeff suggested that documentation for both waffle flags and course level settings should be connected to provide a better user experience.
Evaluation of Existing Documentation and Issues
@pdpinch provided some context on the existing documentation for waffle flags. He mentioned an OEP (Open edX Proposal) that describes the use of feature flags and waffle flags, but noted that it might not be well known or up to date. Peter agreed with @jwitt 's suggestion of having a document that explains both waffle flags and course level settings together with their justifications. He also mentioned a technical documentation document that lists all available waffle flags, but acknowledged that there were issues with its generation and discoverability.
Addressing Flags Lifecycle Management and Naming Issues
@pdpinch acknowledged the issue of flags not being removed when they were projected to be removed. He mentioned the efforts of the deprecation working group to address this and establish a process for code maintainers to be responsible for cleaning up flags. He suggested that formalizing this process would be beneficial.
@pdpinch also raised a concern about the naming of waffle flags, noting that some flags did not correspond to the name of the feature they represented. He suggested that contributors could help by ensuring that the names of flags aligned with the features they represented.
Proposal for a New Course Level Setting
@jwitt discussed the need for a course level setting to address a PR related to the mathjax rendering package. He explained that there were different versions of the package with varying levels of interactivity and bugs. He proposed a course level setting that allowed instructors to choose the version of the package they wanted to use. This would provide flexibility for instructors and allow for smooth transitions without disrupting existing documentation or user experiences.
Plans to Improve Waffle Flags Documentation
@Felipe suggested enhancing the API that provides information about waffle flags by including annotations in the JSON response. This would make it easier to understand the purpose and context of each flag. He also mentioned the possibility of creating a micro front-end (MFE) that builds on this API to allow for easier modification of the flags. @djoy suggested creating an issue in the docs.org repository to consolidate the existing documentation on waffle flags and improve its organization and clarity.
CC @feanil