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.