Dotfiles are like code, and need to be maintained. Some upgrade will break your custom configuration, and then you have to dive into docs again.

I try to make few customizations to the default macOS install, and just roll with the changes coming from Apple. I do have some dotfiles, containing mostly just SSH and ViM configs. But I've already had to fight ViM several times because of it.

Maintenance is amortizable as well. Every time you have to do a deep dive to find out what's wrong, you learn a little more about the state of the art of that particular part of the world. Then you can make a change that is more robust.