In my opinion this is the way to go, documentation close to the code but still indexed in a real knowledge management tool. That's one thing that we are building at Dokkument, but I would be really interested to know more about what you have done, especially how those files are then indexed on Confluence