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?

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?

Time for another rant.

• The vendor people who are intimately familiar with the technology are not interested in writing documentation. If developers won't comment their code, you think they're going to write docs? Besides, their managers have powerful economic incentives to use tech writers who are experts at information packaging, but are pretty far away from being developers.

• One cloud vendor now has over 7,500 pages of documentation overall. A huge investment, consistently written, full of data...and little more than a starting point. The moment you try to really use a feature in a real-world system, it's off to Google and the user forums. Of course, there's enough misinformation on the Web that you'll waste plenty of time. But at least you get the comfort of knowing that other developers are lost in trial-and-error just like you are.

• There's that wonderful acronym, RTFM. Every support organization uses that as their answer to 50 percent of the incoming calls. And that's 'great', particularly when the vendor's docs are wrong, or simply doesn't cover the use case. I recently reported two bugs in a vendor's docs...after several e-mail exchanges, both cases were closed. No resolution, just the message to basically 'go pound sand: the vendor is never going to fix those docs.'

• Docs cover one vendor's technology. But in the cloud, we're all using a range of vendors' technologies plus a bunch of open source goodies. Nobody has the time to document the real environment we're working with -- it's a boil-the-ocean project.

• Docs are like dictionaries (remember, those big paper things&): the information is all there, but you can't effectively communicate just by knowing the syntax and word definitions. The way you really learn a language is by reading real writing (novels, journals, comic books...you know those paper things...) or listening to newscasts, conversations, or songs.

So, tell me again why we're feeling the need for more docs? No developer wants to read them. No developer wants to write them. In the immortal words of Cool Hand Luke, "what we have here is a failure to communicate."

This isn't a matter of "documentation quality" or even quantity. I'm saying that doing big docs is the wrong answer to the question "how do we get developers effective with a new API?"

It ain't gonna be YouTube.

 

1  2  Next Page 

Sign up for CIO Asia eNewsletters.