Nobody’s saying there would be no files anywhere, just not in the application itself. Config files would would be like third party packages that get installed b

Nobody’s saying there would be no files anywhere, just not in the application itself. Config files would would be like third party packages that get installed by an evironment orchestration tool (container, chef, puppet, whatever) for purposes of defining an environment. This way the “API” for a third party providing custom overrides at runtime to config is through ENV vars, not editing files. (Creating a modified config file would be for purposes of creating a whole new installable package that third parties can use. Whoever config files are shipped to, sys admins, end users, yourself on your local laptop, those users would never modify the config file — it would be immutable from their point of view and only extended by ENV). So yes, some files store config somewhere to define environments, but what I’m saying is that when these files are treated as separate installable artifacts outside the app itself, then placing documentation into those config files is unwanted, even an anti-pattern because you’d want them to be in a user guide for people to know how to choose between config files and the use case at a high level, that’s the right place to document why foo is set to 57 or something. Putting human readable comments into the actual environment defining config file is bad because these files can become scattered and out of sync, and it encourages reading the file itself as a source of information instead of central usage guidelines. If you also don’t let people inject custom config into the file (use ENV instead) then there’s no reason for the extra hassle, risk of getting out of sync, or risk of mixed signals that it’s ok to edit the file locally.