API the Docs Amsterdam 2017

One week ago on this day, I attended the one-day, single-track “API The Docs” conference in Amsterdam. “API The Docs” is a world-wide community with regular meetups in different cities, spun off from the “Write The Docs” community of technical writers. Their Amsterdam event was the second full-day conference, and it was run in association with “Beyond Banking”, an initiative of ABN Amro, which is the second-largest bank in the Netherlands. They also provided the venue for the conference, an event and exhibition space called Circl located in the Southern business district (Zuidas) of Amsterdam. The impressive building symbolizes the circular economy by being completely built from recycled materials and served as a great backdrop for a day of interesting talks and networking opportunities.

The Talks

First on the stage, after an introduction by the organizers, was Cristiano Betta, who talked about the “7 Deadly Sins of Developer Onboarding” (a previous version of the talk is available online). Developer Experience (DX), according to him, comes from both information and tools, and whoever wants to provide great DX must be aware of providing neither too much information nor providing too little, too soon, unstructured, unsupportive or incomplete information. When it comes to tools, Betta suggested API providers should “own their SDKs” because whatever people might pull from the package manager for their programming language, which could be a bad unofficial SDK, is their DX. He also reminded the audience to think about having the right success metrics for their APIs (hint: it’s probably not the number of signups, first API calls or even payments).

Up next was Alaina Kafkes of Medium, who talked about building beginner-friendly API tutorials. I really liked her minimalist slide deck with short sentences and emojis. Making developers happy leads to their retention and that leads to the creation of a developer community. Alaina stressed the importance for technical writers to really proofread their tutorials and put themselves in the reader’s shoes. Her advice mostly centered around code samples: they should be complete for easy copy&paste, have as little dependencies and assumptions about the environment as possible and those that are unavoidable should be clearly explained. Tutorials should never be published without first actually trying them out during proofreading. Her last advice was to use inclusive language to make sure that developers from diverse kinds of backgrounds feel welcome.

Koen Adolfs of ABM Amro gave a short introduction about their aforementioned “Beyond Banking” initiative and talked about how they, as a big traditional enterprise, establish an API mindset - a necessity for every bank in anticipation of PSD2!. The steps involved are believing, understanding, enabling, supporting and wanting. When explaining “APIs for dummies”, Koen said that it is important to give real-world examples of how other companies use external APIs as backbones of their business, such as Uber integrating Google Maps for navigation and Braintree for payments. It’s also important to make them understand that an API is a new product for a new customer base. A big hackathon was important for them to get first contact with an external developer community.

Representing MongoDB as one of their 12 technical writers, Anthony Sansone took the stage to talk about streamlining API maintenance. He talked about the difficulties they had with tracking all changes and keeping the documentation up to date with the product. Their first refactoring attempt to improve their approach to documentation explicitly contained no automation because they saw no use in “replacing documentation page files with configuration files”. They just broke everything into smaller pages and strived for more consistency through standardization. Later, they first introduced automation as a skunkworks project in which Swagger specifications were created based on the existing source code of the API, pushing the responsibility for the specification on to the developer. Anthony gave the advice to do this kind of automation for the specification but reminded the audience that the specification is not the whole documentation, there should be an investment in tutorials and standards should be followed.

Emile Bremmer, another representative of our hosts from ABN Amro, gave some examples of using data from log files to understand a developer’s journey and use this information to improve the API and the documentation. Log files can expose inefficient usage, common mistakes and show whether examples from tutorials are actually used or not. He suggested using splunk as a tool to dive into the raw log data and turn it into actionable insights.

The next talk, given by Jessica Ulyate, was also centered around a specific tool, dredd, which can be used to test a Swagger/OpenAPI definition against the live implementation of an API. Data that is not part of the definition can be provided through hooks. Jessica showed how dredd, due to the fact that it runs on the command line, can be easily included in continuous integration (CI) and continuous deployment (CD) processes.

After a lunch break, talks continued with Roman Hotsiy, representing APIs.guru and ReDoc, who asked whether self-documenting APIs are a myth or whether they’re real. He pointed to GraphQL as a way to achieve self-documenting APIs and he also divided documentation into conceptual documentation and technical details, of which only one can be fully self-documented. API description formats can serve as a middle ground between developers who, according to Roman, “really don’t like free-form text”, and technical writers. They can be managed just like code using tools like version-control systems, Markdown and CI/CD. This approach is called “Docs like Code”.

Karen Sawrey, whose presentation had the title “Not all rocket scientists want to be brain surgeons”, told about her experience of being a technical writer at Cossack Labs, a cryptography company. She’s convinced that even a complex topic like cryptography can and should be explained with simple words (and a mascot!) and interactive simulators; she also explained the need to segment the audience, for example in scientists, beginning developers and experienced developers. The talk ended with a recommendation of her favorite tools: Dillinger, grammarly, and draw.io.

“Continous Swagness for your API” was the title that Laurent Doguin of PaaS provider Clever Cloud had chosen for their talk, which mostly consisted of a fast-paced live demo. He said that for them one of the driving forces behind using Swagger/OpenAPI was - apart from documentation - the creation of SDKs, and he demoed a setup of Jenkins as a CI system that automatically builds HTML and SDKs whenever a swagger.json is updated in a repository.

Unlike most presenters which hailed from companies, Nathalie Oostvogels was a Ph.D. student from Vrije Universiteit Brussel who presented her research on inter-parameter constraints. These are constraints on parameters in Web APIs that are not limited to a single field, such as a requirement of presence or a maximum length, but constraints that apply to a combination of parameters. Nathalie has placed them in three groups, exclusive constraints (exactly one of a set of parameters), dependent constraints (constraints on one parameter depend on a property of another) and group constraints (a set of parameters should either be all included or none). These constraints appear in almost all popular APIs but none of the API definition languages (such as OpenAPI, RAML and API Blueprint) have explicit support to formally describe them, and JSON Schema has only basic support which doesn’t cover all possible cases. Nathalie is designing her own extension to express their constraints and is integrating support into TypeScript. This is definitely something of interest to everyone interested in machine-readable API definitions and I would love to see this in JSON Schema or OpenAPI someday!

Aleksei Akimov, who works for payment gateway provider Adyen, talked about the custom API explorer which they built to present their documentation because Swagger UI was no longer suitable. They use OpenAPI under the hood and Aleksei reminded all API providers to actually publish their OpenAPI definitions! Their custom explorer features an adaptive three-column layout, supports multiple products and versions, executable examples and a clean structure for nested objects. It was interesting to see that Adyen uses developer personas in their API design process and that they actually think of the same individual as two different personas at different times - a learning persona and a coding persona. In Adyen’s case, OpenAPI definitions are created based on the implementation. Aleksei stressed the importance of collaboration between developers and technical writers and recommends to always use the latest version of the OpenAPI specification and to launch and iterate fast.

Last but not least was Adam Butler, who talked about DocOps, which he describes as the engineering role in technical documentation. He does exactly that at communications provider Nexmo and described the process in what can only be called the most impressive slide deck of the day. Nexmo maintains their documentation internally in Markdown files similar to the ones used by static page generators like Jekyll, which means they also follow “Docs Like Code”. However, they have their own Rails-based engine with a number of custom Markdown extensions for increased flexibility, and a custom OpenAPI renderer. Everything is automated! For example, code samples in the documentation are collected from language-specific repositories, links are checked and screenshots of the website generated. Adam suggests API providers to always open source their documentation because it encourages contributions, even from unexpected sources - both internal and external. Contribution guides are important to keep the documentation consistent.

Photos of all speakers are available on our Instagram profile.

The Conclusion

APIs are everywhere, but to make them really accessible, a good developer experience is paramount. Great documentation plays an important role. The knowledge and usage of machine-readable API definitions like OpenAPI has arrived in most companies, however the “textbook API lifecycle” in which everything centers around the specification has not. The implementation seems to come first, and documentation follows. Automation of the API lifecycle is still a huge topic and mostly a combination of existing standards and tools as well as custom code. The whole field is still in its early days and there is a lot to be done in terms of better specifications and best practices but one could feel there are many great ideas and investments into improvements of API documentation.

I enjoyed the event not only because of the talks but also it was great to meet the community. Attendees were a mix of different roles though I believe the majority were technical writers. It was a friendly and diverse crowd with a higher percentage of women both on stage and in the audience compared to other technical events. I’m looking forward to more meetups and conferences like this.