Developer Experience
User Experience applied to developers, because developers are people too.
-
Trigger walks through their document refactoring effort.
-
The interactive playground on the front page is awesome — you can immediately tell if the plugin will do what you need.
-
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.
-
Creating useful and clear API documentation can be challenging. Mashery I/O Docs makes it easy to offer a powerful, interactive API learning experience.
-
One of the key findings of the survey was the large number of complaints about current API providers: They’re not serving their developers well. There’s bad documentation. There are problems with services like OAuth. APIs randomly change without warning. And there’s nothing even resembling industry standards, just best practices that everyone finds a way around. As developers, we build our livelihoods on these APIs, and we deserve better.
-
Django is known for its documentation, and the Django author actually wrote a series of posts on his personal philosophy to writing great documentation.
-
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.
-
-
Facebook now offers a Graph API explorer, which includes a way to get an access token for authenticated data.
