Developers Say: “Give Us More Documentation!”

Original Source

Remember when you were young, and your parents demanded that you leave a note if you left the house? Well, now today’s developers and your parents have more in common than ever.

What do developers want more than anything? According to the Developer Insights Report released by Application Developers Alliance, it’s documentation. The report, conducted in conjunction with IDC, points out that one of the top reason development projects fail is because of changing or poorly documented requirements.

It’s not only a reason projects fail – documentation seems to, overall, just be a pain in the neck of many developers. Working in a large company often requires working on or with other developers’ code, a task that is frustrating in itself even if said code is well documented and explained. It’s cited as one of the top ten developer frustrations and some developers even say that they spend more time maintaining poorly documented code rather than actually writing new code.

And it’s not just documentation from higher ups or other developers that frustrate programmers – sometimes API management vendors don’t document things well either. In a review of Forrester’s 2014 report on the top API management platforms, customers said that they were disappointed with the documentation provided by even some of the most veteran vendors.

People are listening to these demands, thankfully. WSO2, another API management platform reviewed by Forrester, says that one of the things his company prides themselves on is solving the “poor documentation barrier.”

“You can go to our API store, which is very similar to a Google Play store or an Apple iTunes App Store, and you can view information about the API…read the documentation,” says Haddad. “We have a lot of ideas on the roadmap and that we are incorporating into the API management platform, such as better notification features so that you can let the community know that a new version is available or that new documentation has been released.”

Vendors such as Alpha Software are stepping up the documentation game as well. At the 2015 Alpha DevCon conference, co-founder Selwyn Rabins announced – to the sound of thunderous applause, no less – that they are actively looking to solve the “documentation scatter” problem.

“The documentation is pretty good,” says Rabins. “It’s just not always clear where to find it.”

To solve this, Selwyn and his team are working on enabling easy (read: fast) searching of existing documentation topics and adding features to make it simpler to edit and contribute documentation in order to ensure that information is up to date.

“Alpha is very large,” says Rabins. “Finding documentation is going to be a big boost to productivity.”

In terms of documentation within organizations themselves – well, that is on clients and developers to just hear the calls of their associates. Hopefully the rise of open source development can help, but in the meantime, it seems, one of the best things that developers and clients can do for their peers is, as your parents would say, “leave a note!”