The "core" of msbuild - targers, items, properties - is well documented. The actual work in normal cases is done by the vast hinterland of pre defined targets, and it's those that are badly documented. I've wasted several days reverse engineering 'ProjectReference' and only just found its detailed documentation. Fortunately you can read the source; unfortunately when you have to.

I think making it open source has come with a cultural change that's still propagating. It means not just defining the "Microsoft way" to do things but coping with myriad use cases turning up in the issue tracker.

If you think the "core" is well documented, link me the documentation which lays out all the built in targets involved in a standard c# project. Or even just a doc which describes the differences between PreBuildEvent, BeforeBuild, BeforeCompile, etc. As far as I can tell, this only exists as occasional comments in the .targets file. Msbuild documentation is horrible, without exception. When they occasionally document something it tends to miss half the optional flags and they never link the source code so it's up to you to find and correct it.

This is exactly what I"m talking about, usually I have to have Visual Studio generate a project file and see what it did.

Using XML as a general purpose programming language is also very ick.

You can write your build scripts in F# with the excellent Fake library or Cake for a similar C# DSL.

It gives you the same IDE experience for your build scripts and your code including REPL for experiments and a debugger when needed.

since it is .NET Core they are as cross platform as your other code.