News Stay informed about the latest enterprise technology news and product updates.

Microservices: The new documentation nightmare?

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.