Microservices Matters

Sep 18 2015   2:31PM GMT

Developers say: “Give us more documentation!”

Fred Churchville Fred Churchville Profile: Fred Churchville



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!”

Do you experience documentation issues within your organization? Let us know what they are – and what you plan to do about it.

5  Comments on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.
  • cobiacomm
    What are your most important, must-have API documentation attributes that are hard to find?  
    235 pointsBadges:
  • FTClark

    The documentation problem has been around forever! It is sad and destructive when the documentation is sparse to non-existent.

    Problem 1: The truly skilled software engineer needs to be as adapt at writing English as at writing code. They need to spend about half their time writing documentation to be truly successful. It is sad that some so-called engineers appear to be unable to read and write plain English and assume nobody else does either.

    Problem 2: In the days of smaller systems the documentation was a simple book that I would just read cover to cover. Systems have grown so large that it is impossible and non-productive to try to read it all. There is no time to even do that. Good organization and good search tools are needs second only to the primary existence of good documentation.

    1,280 pointsBadges:
  • AugustM
    People keep looking to automation of one form or another to solve the documentation gap, but it can only go so far. We may not have reached the limit to how much automated systems can help, but there is indeed a limit. Fundamentally, the challenge is to get information out of the heads of one set of developers/engineers and into the heads of another (usually much larger) set of developers/engineers. The limit is caused by the fact that developers cannot write with the level of clarity that they need to read. In between is the Technical Writer, the Documentation Engineer, the Development Writer, whose value added is to take what developers write or brain-dump in interviews and turn it into something comprehensible to those who do not already know what it is supposed to say, something that truly informs other developers who are coming to the topic cold. It's going to be a while before comprehension is automated.
    10 pointsBadges:
  • cobiacomm
    good comment @ftclark about system size.  breaking the system up into smaller atomic units would aid understanding.  For example, an eCommerce system could be reduced to customer, product catalogue, order, invoice, and shipping.   The interconnections then need to be properly documented :) 

    @augustM,   automation is only as good as the meta-data into the tooling.   Unless DevOps teams establish a meta-data taxonomy, documentation automation will be incomplete (as you mention).  

    From a documentation clarity perspective, establishing a template describing 'what API topics and questions should be answered' is a good first step.  Peer review for clarity will help close the communication gap when relying on engineers instead of professional writers. 
    235 pointsBadges:
  • TheRealRaven
    Determining what is and what isn't an "API" might be the best first step. E.g., I have a proc named get_Adopted_Authority_Programs_Status(). It may be called from any program in the app or called within the accept_Adopted_Authority() proc. Without giving details of its function, how would we decide if it's an "API" or not?

    ...establishing a template describing 'what API topics and questions should be answered' is a good first step.

    In some respects, that's a big part of choosing what is and isn't an "API".

    Of course, it leads to another question: Why is this topic limited to "API"? Doesn't it apply equally to every program, proc, table, view, etc., that will be referenced by some other object? If not, why not? Is there a reason that "API" is singled out at all?
    36,340 pointsBadges:

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: