Which toggle annotations should be published to readthedocs?
See the how-to for annotating toggles for more info on all of the annotations.
See the edx-platform toggle documentation on readthedocs to see what annotations are currently included. At this time, it includes the name, default, description, and optional warning.
Here are some proposals around possible additions:
- toggle_implementation: I propose this be included, because simply knowing that a toggle is a “DjangoSetting” vs a “CourseWaffleFlag” gives a lot of information around the capabilities of the toggle and how and where to configure it, once you understand each type of implementation.
- toggle_use_cases: We might need a separate conversation around this annotation. I would want to know which toggles are temporary, which might be a separate flag. We need to determine if the permanent use cases are important to capture and publish as separate metadata. I would argue that if this data is not important enough for the docs, we shouldn’t be collecting it in code either.
- toggle_target_removal_date: This could add even more details in the case of a temporary toggle.
- toggle_tickets: There is a separate discussion topic on this particular annotation. As long as we have this annotation, I would include it in the docs. See additional authoring concerns detailed below.
Additional authoring concerns:
I think it adds to much complexity to expect toggle annotation authors to remember which annotations are published and which aren’t. Additionally, if we decide some are not published, it means the author would need to duplicate any relevant information in the description, which adds more risks of incorrect documentation, and make the metadata useless in certain cases.
If we don’t think certain metadata is important (e.g. permanent use cases?), we should remove it rather than ignoring it, which just makes the problem worse.
The only annotation that I can see continuing to leave out is toggle_creation_date, which serves its purpose with other tooling, and may not be important to operators or other readers of the published docs.
Let me know your thoughts.