Trigger walks through their document refactoring effort.
When I surveyed developers about what makes for great documentation, many folks loved docs that let developers comment on each page. In-documentation comments can be a great way to encourage developers to post snippets of helpful code for a particular feature or find out there are mistakes in the docs.
However, they also have their cons - they require moderation (spam!) and worse, they can lead to community fragmentation, which can lead to no community at all. jQuery originally embedded comments on each of their documentation pages and after experimenting with them for a year, they decided to turn them off. They wrote a great blog post with their learnings. Kudos to them for trying it out, and for being transparent with their decision to turn them off.
It doesn’t mean that in-doc comments never work— but it’s certainly a feature that you should consider carefully before adding, and re-evaluate later to see how it’s working.
An increasing number of popular libraries are hosted on GitHub, where they can take advantage of the formatted readmes and wiki for documentation and the issue tracker for bugs & feature requests. They can also encourage people to fork and improve the projects themselves (like SammyJS does with their docs). Besides the built-in github tools, there are also several third party tools integrated with github JSFiddle will load fiddles hosted in github repositories, and Read the Docs will generate nice documentation for github repositories.
Given the number of tools available, GitHub seems like a great choice for open-source projects out there that want to provide a positive developer experience.