The existing documentation of IDL in src/mongo/idl/README.md contains useful information that is in some cases difficult to discover. As a recent example, I needed to figure out a way to include a C++ file in the resulting generated files from an IDL file. The answer, cpp_includes, is mentioned in src/mongo/idl/README.md but under the Global header. That makes sense from a topic categorization perspective, because the cpp_includes field does go under the global top-level field, but it's unintuitive to search there when the question is "how do I include an external header in my IDL generated files."

We should extend the documentation to more helpfully and straightforwardly answer questions like these, maybe as an FAQ sidecar to the main documentation file.