Swagger goes part of the way towards solving this problem, at least for REST apis: <a href="http://swagger.wordnik.com/" rel="nofollow">http://swagger.wordnik.com/</a>. It's a little annotation heavy for me - I'm guessing you want something that's generated almost entirely from code introspection. And it obviously doesn't work for library code. But I think the UX for an implementer is a great one.<p>I do love Readme Driven Development (<a href="http://tom.preston-werner.com/2010/08/23/readme-driven-development.html" rel="nofollow">http://tom.preston-werner.com/2010/08/23/readme-driven-devel...</a>), and Github helps here with its per-directory readme displays, but keeping up with these over the duration of a project is obviously a problem, as you note.