<VR>

  • Home
  • Talks
  • Podcast
  • Blog

Documentation for Frameworks and APIs

Published on Mar 08, 2014

🚀2 mins to read

  • notes
  • articles
  • survey
  • documentation

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

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.

Built with passion...

React

Used mainly for the JSX templating, client-side libraries and job secruity.

Gatsby

To enable static site generation and optimize page load performance.

GraphQL

For data-fetching from multiple sources.

Contentful

CMS to store all data that is powering this website except for blogs, which are markdown files.

Netlify

For static site hosting, handling form submissions and having CI/CD integrated with Github.

Images

From unsplash when they are not my own.

..and other fun technologies. All code is hosted on Github as a private repository. Development is done on VS-Code. If you are interested, take a look at my preferred dev machine setup. Fueled by coffee and lo-fi beats. Current active version is v2.11.3.

</VR>