GitHub Hosting Documentation for Dozens of APIs

Adam DuVander
Sep. 30 2013, 12:00PM EDT

GitHub is not just for code anymore. There are 84 APIs in the ProgrammableWeb directory that host their documentation on the site that makes code social. That count includes the official GitHub API, of course. What's especially interesting is that hosting docs on GitHub is not just for small startups, side projects or entities with an open source ethos. There are some big companies choosing to put forward information about their API right where someone might be looking for code.

BasecampAmong the companies hosting documentation on GitHub is developer favorite 37 Signals. The company previously sent devs to its own portal, but now the Basecamp API is documented on GitHub, along with the Campfire API, Highrise API and Backpack API.

MoodstocksOther companies with docs on GitHub are the New Relic API and the Moodstocks API. Less surprising, perhaps, are more community-oriented companies. For example, the Khan Academy API and many Sunlight Labs APIs are using GitHub for docs.

An additional benefit of hosting on GitHub is the opportunity for community collaboration. The same way developers work together on open source code, they can offer tweaks to the docs. SendGrid (where I work), for example, does not host docs on GitHub, but did recently open sourced its documentation.

Data on the number of APIs to use GitHub for docs can't be accurately broken down by year because some launched with other documentation solutions before moving to GitHub. For example, the Backpack API, launched in 2006, is older than GitHub itself. That said, the chart above shows a trend toward more APIs using GitHub. 34 of the APIs added in 2012, for example, use GitHub for documentation.

What benefits and drawbacks do you see? Would you--or do you--use GitHub for documentation?

Adam DuVander is Developer Communications Director for SendGrid and Contributing Editor of ProgrammableWeb. Previously he edited this site and wrote for Wired. You can follow him on Twitter.

Adam DuVander Hi! I'm Developer Communications Director for SendGrid and former Executive Editor of ProgrammableWeb. I currently serve as a Contributing Editor. If you have API news, or are interested in writing for ProgrammableWeb, please contact editor@programmableweb.com Though I'm a fan of anything API-related, my particular interest is in mapping. I've published a how-to book, Map Scripting 101, to get anyone started making maps on websites. In a not-so-distant past life I wrote for Wired and Webmonkey.

Comments

Comments(1)

The biggest two issues I see are "ownership" and "scale".

- It may/may not be important to you to "own" the experience of your API docs beyond the relatively simple templates of GitHub.

- When your docs get unruly/massive amounts of info. A simple hierarchy reaches it's limits, you start wanting robust search, and possibly integration with other tools/IDE's.

One can make the case, that GitHub's simplicity/speed win out over ownership, and that massive API docs are code smell. Eye of the beholder...