Microservices Matters

Dec 11 2015   3:32PM GMT

Microservices: The new documentation nightmare?

Fred Churchville Fred Churchville Profile: Fred Churchville

Application development

Recently I wrote a post on the issues surrounding development documentation and product specifications. At this year’s JavaOne Conference in San Francisco, I attended a session on building microservices and asked presenter Reza Rahman, Java EE Evangelist for Oracle, how microservices will impact the documentation issue.

“It’s going to get worse and worse…depending on how fine-tuned the services are,” Rahman said. “These APIs don’t simply document themselves.” The problem is exacerbated even more by the use of REST as opposed to traditional SOAP, since documentation will have to be updated to coordinate with this potentially unfamiliar language.

So be warned, developers. Breaking down apps into services has gained in popularity over the past year, and it may only be a matter of time before your management is demanding that your team start picking up on the trend. It might not be a bad idea to create a plan for how to keep documentation straight.

“Best practices are no different than before,” said Rahman. “You have to do what you need to do…document the stuff, make sure you send it out and make yourself available for your users and so on.”

One participant asked about the use of Swagger for documenting APIs, which Rahman said was fine to use. Other tools to consider include Mashape, Mashery, 3scale and Apiary.

You can view Reza’s presentation for yourself on SlideShare to learn more about remaining realistic when it comes to using microservices. Also, let us know how you plan to deal with a potential “microservices documentation fiasco” or how you deal with documentation issues in general by commenting below.

 Comment 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.

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: