

JavaScript Documentation Sucks - hbrundage
http://harry.me/2012/01/22/javascript-documentation-sucks/

======
jmreidy
Swagger goes part of the way towards solving this problem, at least for REST
apis: <http://swagger.wordnik.com/>. 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.

I do love Readme Driven Development ([http://tom.preston-
werner.com/2010/08/23/readme-driven-devel...](http://tom.preston-
werner.com/2010/08/23/readme-driven-development.html)), 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.

------
secoif
You _can_ repurpose Docco as a running commentary for library usage or for
examples. This combines the readability of Docco with the awesome usefulness
of usage examples.

It also allows you to easily run your example code as part of your test suite.
Nothing more frustrating than broken example code.

e.g. <http://dev.groupdock.com/kin/>

