It seems to me that the issue with auto-collected code is that, if done well, it captures the behavior of the code itself. However, it doesn't capture the specification of how the system should work (as opposed to just how it does work) or the higher level design and strategy of the system.
I agree with that too. There needs to be a lot of pure narrative in addition to the auto-collected API Docs. My big project has User Guide (with intro, vision, tutorials and how-tos), Developer guide (with architecture description, requirements specs, implementation overview) and then auto-collected API docs with all the details of how it's currently implemented. In the "notes" admonitions throughout the API docs, there's a some historical information and description of why it is the way it is and how it should ideally be (as appropriate). This feel like it works pretty well. Then again, I wrote a lot of it so I'm biased.
There should be a roadmap somewhere as well, possibly in a Wiki or the developer docs.
