A lot of our thinking at edX about how to live in a multi-service world has been to try to keep everything about a service in the repo for that service. I know this doesn’t jibe with how things are organized today (for example, Ansible playbooks in a central repo), but it is where we’d like to go.
My own strategy for documentation is to try to keep the words near the things they describe. This makes it easier to keep the words in sync with the code, easier to find the words when they need updating, and easier to know the words exist and need updating!
It’s harder to find the words to read, but tooling can help solve that problem as part of the publication process.
So I’m not sure a centralized doc repo with settings for edx-platform is the best approach. What else could we do? Is there a reasonable way to document the edx-platform settings in the edx-platform repo?
Probably not. I also thought about that and decided we would be able to move the docs and tooling elsewhere once it is more mature. This gives us a better possibility to experiment and try things before deciding moving the content upstream.
I’m hoping that the docs for settings are not in separate .rst or .md files, but are in the .py (or whatever files) where the settings are defined or used. The closer the words are to the code, the more likely the words will be written and maintained.
Maybe we should start by making a fuller description of what we mean by “document the settings”: what settings, and what needs to be said about them?
Even if the docs are in each service’s repo though, can we have a single site that shows the rendered version of all the docs? (Ideally versioned by named release or master). Currently some docs are at Developer Documentation (edx.readthedocs.io/projects/edx-developer-docs) but that doesn’t include (things like) the autogenerated API documentation nor does it have links to each service’s documentation (ecommerce, credentials, discovery, blockstore, etc.) It’s also fairly out of date, e.g. “Options for Extending the edX Platform” does not mention django app plugins, [django] IDAs, nor microfrontends.
One of the ideas I enumerated in my documentation minifesto was to write words near the code, and then use tooling to publish the words where it was better for readers to find them.
There’s a lot to do to make that happen, including just deciding on the best approaches. OEP-19 Developer Documentation covers some of this, but it might need revisiting.