July 2016 update: I’m resurfacing this entry, first posted in March 2014, in light of StackOverflow’s launch of their Documentation hub. They’re one of the best-positioned companies to tackle at scale the challenges I explain below. One of their key areas of focus is code examples, which is exactly what the doctor ordered.
The explosion in the quantity and quality of both commercial APIs and open source projects is a huge enabler for digital start-ups and small businesses. Instead of painfully rolling your own version of, say, sending email newsletters or displaying a media gallery, in many cases “there’s an app for that.” However, behind the numbers, the very uneven quality of the documentation made available with said APIs, plugins, and packages, is a serious impediment to fully realizing the productivity gains promised by these vibrant ecosystems. (Wow this sounds way too much like an enterprise software whitepaper!)
Typically documentation takes shortcuts by implying bits of knowledge that the reader may not have, skipping necessary steps, leaving out important nuances, or providing incomplete and obtuse examples. These issues are compounded because of today’s development by integration more than pure coding. I’ve been thinking about how this could be alleviated. Read More