I just filled out a developer survey form shared by smashing magazine’s facebook page. Its about documentation and what’s important for developers. I felt like expanding on some of the points.

Real world examples

The most important aspect of documentation for me is the use of real world examples. I want to use your plugin or framework in an application, in production. I think having more real world examples and use cases, helps me make my decision faster.

Document all the options

A lot of times, I notice that some of the plugins have an amazing amount of capability. However, the documentation reflects this very poorly. I understand that creating examples for all the cases might be crazy, however, listing all the options is an absolute must.

Mobile phones

I want to be able to view the documentation on mobile phones. I could be sitting in a train or at some other place away from my laptop or PC. I could just come up with a way to solve a problem. I want to be able to quickly login to the docs page and see if its possible. While most recent websites, especially open source docs powered by github are usually responsive, the code part isn’t. The easiest thing to do with code blocks on such pages is to add a horizontal toolbar.This works in a lot of cases but I have had usability problems with some of the websites, where I simply cannot scroll to the other end. Worse, I was able to replicate this on my desktop while shrinking the viewport. Horizontal scrolling was just useless. It has to be tested out. Please!

Contributions.md

I hate it when I see a plugin and I see a typo or a bug that I can resolve. I have the time to make that PR but finding out how to contribute is so complicated sometimes, that I give up. What’s worse than that is having a very banal and overly-generic contribution readme

Links to Github

I thought this was a no-brainer! You have an open source project, a free plugin. The source code for this plugin is on github. Being able to access that is important for me. I can look at what issues are reported, how often commits are made, how active the discussion is. I have recently been frustrated with one such jQuery plugin, that does not link to github on its page. I was totally lost!

If you are a developer, I urge you to take this survey, so we can get a consensus on what everyone feels.