Subscribe / Unsubscribe Enewsletters | Login | Register

Pencil Banner

Cloud development documentation insanity

David Taber | Dec. 14, 2011
Everybody knows that complex technology needs documents and training materials so that developers can effectively use it. In the cloud, this need is magnified by the fact that developers have to work with several languages at once (HTML, JavaScript, XML, CSS, jquery, Ruby, PHP, SQL...the possibilities are endless). So developers need more docs, right?

Training courses? Not bloody likely.

It's simple: Speak the language that developers around the world understand. Code.

A Modest Proposal (Google it...)

Vendors, divert 2/3 of the money you spend on writing developer docs in India to fund coders in India. Create a serious pool of code samples that actually do something (rather than the usual snippets that can't actually execute because they're missing that "obvious" constructor). Instead of writing about design patterns and best practices, show them in code (with enough comments for the novice to follow). Post working applications in demo systems that registered developers can get to. Show your stuff off.

Yes, the vendor's lawyers will whine about the risk of an attack from patent trolls. So put all those samples in open source. Vendors, invite your developer community to improve and extend your code samples -- particularly with cross-language examples using infrastructure that is outside of (but frequently used with) your API. Provide incentives for the best contributions (sometimes, all you need is to offer recognition on your blog).

And yes, some of your system integrators will be all bent out of shape because you've made it easier for the customer to be self-sufficient. But by democratizing the knowledge around your APIs, you'll be greatly growing the pie: there will be more successful customers and more economic benefit for all. In the long run, those same system integrators will have more to do, even though they won't get the easy kills from exploiting hidden knowledge about the basics of your API.

Customers, judge products by their code samples, and let the vendors know you're doing so. Ask the sales rep to get his SE on the phone, and grill them on where to find the repository of code samples for their product before you buy. Don't let them off the phone until you get that URL. If they don't have one, start laughing at them.

Humor is, after all, the best antidote.

 

 

Previous Page  1  2 

Sign up for CIO Asia eNewsletters.