Sparky, I don't have any experience myself with the history of shell SDK documentation, but I think there are explanations for quality of SDK beyond the two you propose (based on what I saw developing parts of the Sharepoint Portal 1.0 programmability model)
It all comes down to resources. Every team has finite resources, and Microsoft is no different from any other company -- you can't just assume that you can magically double the size of a team overnight to cover all the work you'd ideally like to do.
If I were the SDK team, and I had thousands of APIs I had to prioritize between for sample writing and documentation, I'd look at the following:
1) breadth of API usage. Is this something that every developer will need to use? Something that only a handful will ever touch?
2) expertise level of anticipated customer. Is this an API that we expect to be used by an entry level dev, or is typically used only in scenarios where you'd expect to have an experienced expert writing the code? [there's probably some correlation between the answer to #1 and this one]
3) complexity of API. Could you figure out the right way to use this API from intellisense hints alone? Or does it need extensive documentation, best practices, etc.
4) complexity of work to document and create samples. Is it just one object with a few methods where I can show best practice usage in 50 lines of code? Or is it a big collection of inter-related objects where I'd need a real world sample app to show how it all fits together?
Again, I don't have insight into how the SDK and shell teams made particular decisions about documenting these APIs, but you can imagine a set of answers to the four questions above which would lead a reasonable person to conlucde that extensive documentation of these APIs might not be at the top of the priority list.
Also, I think I heard Chris say in the interview that they really are trying to improve this going forward, with better SDK support this time around in addition to designing APIs that are easier to use, and easier to use right, from the start.