Oh, that is actually the part I do agree with. I don’t think everyone will, but I do actually think JSON is easier to read and write (correctly) than YAML. I specifically wrote that JSON cares the least about that, because it was designed to just serialize JavaScript objects into strings and back. As far as its original purpose is concerned, no one would ever need to hand-edit JSON. Which is also why it doesn’t support comments (which is still somewhat of a dealbreaker for a configuration language, although I guess for your proposed workaround, one could potentially use a JSON flavor which supports comments; potentially, you can even write your JSON in the YAML file with comments directly and then not convert it, since YAML is a superset of JSON).

As for documentation, yeah, it is possible to convert, but it makes it more annoying, particularly also if you then can’t easily re-use configs in another project. And if you’re working in a team, having to explain to all your team members, how they can convert the official documentation, is also not really acceptable…