This task is about designing the documentation for MediaWiki config (wg globals) in the world where DefaultSettings.php moves into YAML. Resolving this will not be a blocker for the settings loader project.

Status quo

Source of truth for MediaWiki configuration docs for developers is currently in PHPDoc in DefaultSettings.php. It is the rendered via doxygen into a page like this I do not think this page is accessed often since it's berried under Files in the table of contents. However the docs for individual globals are linked via @see $wgBlaBla PHPDoc annotations.

Additionally, a page on MediaWiki.org exists. This set of pages seem to be maintained manually. This documentation is aimed more towards system administrators of MediaWiki installations, not developers.

Moving towards YAML

Whe ver convert DefaultSettings.php to config-schema.yaml, we will loose the autogenerated docs. @see $wgBlabla links will no longer work.

Here's what needs to be done to maintain the status quo:

1. Autogenerate docs/Configuration.md from config-schema.yaml with a new maintenance script. This file will be automagically picked up by mwdocgen.php and included in autogenerated documentation.
2. Create a structure test verifying that the docs were regenerated after the config-schema.yaml is changed.
3. The @see $wgBlabla links will no longer work and it's a good thing, since we're transitioning from using globals for the configuration all over. Linking docs to configuration can be done with @link now in a form of @link Configuration.md#BlaBla. We could also consider adding a custom Doxygen tag for this.

MediaWiki.org configuration documentation will not be changed as a part of this as its maintained manually.