Willr - you asked about making the docs better. Some thoughts:
The docs would be a lot better if the most common config settings were listed, to get people going. Also a list of common config settings that can't be set in the yaml files & why would be handy & would reduce the learning curve.
eg, http://doc.silverstripe.org/framework/en/3.1/tutorials/4-site-search still shows to use the static method. why?
I wouldn't think a description of how yaml works in the job of the SS docs, but a handy link would be friendly.
read the source code is good general advice but its pretty hostile to new users.
Silverstripe has a lot of documentation, but a common gripe is the documentation isn't very good. Thats a concern for sure. for an example of great docs, check out either the laravel or cakephp sites. They generally have a good general intro to a section & the concepts behind it, backed up with in depth specific sections with code examples for common uses with the context shown.
finally, the silverstripe.org pages rarely load first time. It might be better if they were built with a static generator for some uptime & performance.
in terms of handy links for this specific issue, i found this: