API the Docs Recap

Hi, my name is Serizawa and I’m a technical writer in LINE. LINE has a program that allows engineers to attend overseas conferences on company expense so that they can grasp the latest technology trends. In this article, I’d like to share my report on API the Docs, the API documentation conference that I attended, thanks to the program.

API the Docs is an event specialized in API documentation and is held around the world for technical writers, API developers, product owners, and evangelists. It is a place for sharing knowledge and exchanging opinions on the latest best practices and trends in documentation; documentation is undeniably an important element of a developer experience.

The API the Docs I attended was held at the Mozilla office in the center of Paris on April 24th, 2018. Ten presentations were provided, all spoken from different perspectives, by API experts, content strategists, software developers, and others involved in developing and managing API documents and developer portals. The presentations ranged from general discussion of essential elements for developer portals, to concrete information such as techniques for generating documents using OpenAPI and hardships about portal platform transition. In this article, I will introduce the ones which were particularly interesting to me as a technical writer responsible for the API documentation of the LINE Platform.

You can check the outline and materials of each presentation in the Pronovix’s website, API the Docs Paris 2018. Please take a look—I’m sure that you will find topics interesting in some way, especially if your work is related to using public API.

The State of Banking APIs Portals in the PSD2 Forced Innovation Context

This presentation was made by Mehdi Medjaoui, Lead API Economist of API Academy.

PSD2 (Payments Service Directive 2) is a directive prescribed by EU and became effective in January 2016. This directive is expected to promote FinTech services and enhance the convenience of customers, as it requires financial institutions to provide third parties with customer account information, if the customer agrees. PSD2-compliant financial institutions have opened a developer portal and published APIs that can be used to perform operations such as acquiring account information and transferring money. Mehdi compared developer portals of eight banks that are PSD2-compliant and made clear what kind of functions were provided by advanced portals.

There were big differences between the developer portals compared, and Mehdi pointed out that regardless of the vast range of their services, none of them completely satisfied the elements expected by third-party developers for a developer portal, such as seamless process for registration and a sandbox for you to actually test APIs. He also indicated that the portals introduced had room for improvement, to keep up with Stripe and Square, leading companies of the FinTech industry.

Mehdi’s slides included the elements expected by third-party developers for a developer portal and examples of easy-to-use portals. I found the presentation very useful as I learned functions that would certainly make things convenient if implemented—I hadn’t even thought about those functions, having chased by my daily work.

Architecting Developer eXperience: What Docs Does a Developer Portal Need?

This presentation was made by Kathleen De Roo, Technical Writer of Pronovix.

What does it mean to architect a DX (Developer eXperience)? For developer portal DX, it’s about designing to provide a variety of documents so that developers can deal with the problems they face at each stage of the development cycle, by themselves. In this presentation, Kathleen showed best practices covering documents categories required by developers at each development stage, landing page designs to help developers easily access various documents to serve their needs, items to prepare for improving the reliability of the developer portal, and many others.

From the beginning of product development with public APIs, to releasing and running your product or services, a developer portal becomes a self-services support hub for third-party developers (If you have a well-constructed portal, the number of calls requesting for support will be reduced. For example, at Stripe which I have mentioned earlier, it is said that less than 10% of their customers contact customer support). In order to provide an excellent DX, it is necessary to prepare documents of various categories that is right for the product’s lifecycle, from testing stage, through trial stages to the actual operating stage. For example, developers who are eager to try out an API will need to comprehend the whole picture quickly and check the behavior of the API. On the other hand, developers who tend to be rather practical—especially if the API is not free—will want information on price plans. Developers at the implementation stage will make use of FAQ pages providing answers to common problems, and a forum where they can share questions, answers and opinions with other developers.

One of the most impressive point given by the presentation was that when you think about the goal of a developer portal, you should aim to make third-party developers fans of your API. In order to run a developer portal, merely having a set of complete documentation is not enough. It is essential to cooperate with the Developer Relations team, which is responsible for revitalizing the developer community for your products and spreading information through blogs and such.

Going to Infinity and Beyond Documentation with OpenAPI

This presentation was made by Taylor Barnett, Lead Community Engineer of Stoplight.

The OpenAPI specification (formerly known as the Swagger specification) is an open standard for describing REST APIs. In this presentation, Taylor showed that you can use OpenAPI for various purposes. It can support designing API, creating a mockup, and checking whether you have implemented your API according to the specifications.

With OpenAPI’s structured approach, writing documents is simpler and quicker, and guarantees consistency for the terms you use, compared to writing from scratch, without OpenAPI. In fact, many are already aware that it is a convenient documentation tool. However, the fact that it can also be a good tool for improving API developers’ DX doesn’t seem to have much attention it deserves. Taylor focused on this point and explained the advantages of incorporating OpenAPI in an engineer’s point of view, in each of the four areas; designing API, creating a mockup, testing, and getting feedback.

The common advantage of all these four areas is that OpenAPI enables you to check your API before you have a complete outcome, prevents omissions with the help of automation, and supports collaboration between developers by providing a common format. There already are some useful tools available such as Dredd, a framework to check the gap between implementation and documentation, and speccy, a linter. Just like the title of this presentation reads, it seems there is great potential for API development with OpenAPI.

Takeaways

API the Docs was the first overseas conference for me, and I was impressed by the variety of expertise required in the field of API documentation. Creating content that is easy to understand is a quite a small part of technical communication. I strongly felt that it is necessary to have experts in various technical fields to work together as a team to maintain an easy-to-use and reliable developer portal and continue to improve its technology base in a more efficient way.

At the same time, I also learned many specific tips to make our LINE Developers site better. I’d like to improve the site one by one by starting with what I can do now.

By the way, LINE is hiring technical writers for English and Japanese documentation. If you are interested in pursuing the possibility of technical documentation with us, please apply through the links below.

We look forward to getting applications from enthusiastic technical writers.