It seems that there is a history of ways to build packages and the docs probably need to explain now versus then so that you can beware of what other people have written in the past. They also need to be comprehensive enough that you're not looking for other people's answers that may be out of date.

Back to my original point - I don't think Rust is going to fix this.