API THE DOCS, AMSTERDAM

The Seven Deadly Sins of Developer Onboarding

Cristiano Betta

Developer Experience designer, betta.io
 

What is DX?

Developer Experience is the journey between a first site visit and a successful API integration and is driven by tooling (like SDKs) and information (documentation around the tools).
 

7 DX sins and 7 tricks to tackle them

The 7 sins

• Too much information
• Information that comes too soon
• Too little, too late information
• Unstructured information
• Unsupportive information
• Incomplete information
• Out of control tooling

The 7 takeaways

• Prevent cognitive overload
• Only ask questions when needed
• Present information with structure
• Present information on time
• Tell the best stories
• Tell the whole story
• Own the whole story

Throughout his whole presentation, Cristiano provides us with real-life examples and lists solutions that companies like Braintree, GitHub and Amazon apply to tackle DX problems.

Find a summary of Cristiano's talk on his website.

Building Beginner-Friendly API Tutorials

Alaina Kafkes

Software engineer at Medium
 

Think like a reader: proofread your tutorials

Write to retain new users. Optimize your docs for novice users via beginner-friendly tutorials. But how can writers look at content they already know anew? In her talk, Alaina sums up 7 guidelines with loads of tips to follow and includes practical examples taken from companies like Clarifai, Twilio and GitHub.

1. Offer a quick start
2. Perform a tech audit
3. Remember your environment
4. Share next steps
5. Anticipate errors
6. Stick to the standard library
7. Use inclusive language
    

Quality tutorials result in API user growth

Proofreading improves tutorial quality → quality tutorials lead to beginner retention → retention fosters a healthy community → community augments API user growth.

Open Banking: Let’s Go Beyond Banking

Koen Adolfs

Product Owner of Open Banking at ABN Amro

ABN AMRO recently launched their API developer portal Pronovix also worked on. We are all super proud of it!
Koen showed us what it takes in a large financial organization to get such an initiative supported and realized into a live platform, and how they see their future path as an aggregator of many sectors. Albeit his presentation is not to be published in its entirety, we got approval for this one slide.

Writing for Scale: Streamlining API Documentation Maintenance

Anthony Sansone

Senior technical writer at MongoDB

How MongoDB improved its documentation

Unclear documentation can lead to more adoption friction and often means that organizations with larger deployments face challenges with using your application at scale. At MongoDB, the API documentation was difficult to use. When trying to update that documentation, Anthony and colleagues discovered that how they managed those docs was unsustainable. In trying to help their users scale, they saw that they needed to help themselves scale the documentation:

• Refactor the docs: what do we have and what do we need to change?
• Refactor the process: do research before revising the process,
• Plan more, execute less,
• Establish own best practices to make the API specification consistent and complete,
• Schedule the work: prioritize what to convert,
• Automate the API specification and document how to use the API.
   

7 takeaways from MongoDB’s docs process

1. The API specification is not the API docs, only part of it,
2. Automate the API specification,
3. Work with your engineers on revising the API specification,
4. Set and stick to standards,
5. Test your API: use it to be able to explain it on multiple platforms,
6. Plan for incremental rollout,
7. Invest in tutorials: focus on tasks and activities.

Viewing a Developer’s API Journey through Logs

Emile Bremmer

Developer at ABN Amro

How to process feedback for ABN Amro’s developer portal

ABN Amro uses the Splunk tool to turn raw data into searchable and visualizable information.

This enables the team to investigate:

• how developers work with the portal and reach success,
• what the repetitive errors are,
• what can be done to improve efficiency via the documentation or error descriptions,
• example API calls, developer profiling, common mistakes.

Challenges remain. Next steps on the agenda include log data, before/after comparisons, machine learning opportunities.

Contact Emile directly (emile.bremmer@nl.abnamro.com) with your own feedback.

From dreadful to Dreddfull: Automated Testing for your API

Jessica Ulyate

Developer and Product Manager
 

How to test automated API documentation

APIs need good documentation, and to keep your reference docs up-to-date you need to test them. Dredd is a program that tests API references in specification languages Swagger/OpenAPI Initiative and API Blueprint.

Jessica talks about how to use Dredd in practice and some of its perks, like:

• using hooks to modify request data,
• testing your docs continuously with CI/CD.
   

Test docs to make life simpler

• Automated testing the API reference docs is something that - with the right tooling - even people in not so large organizations, with little financial support can do,
• API reference docs are the basis of your documentation and have the highest potential for generating errors.

Check out: Keeping documentation honest - an article recommended by Jessica.

Self-documented APIs: myth or reality?

Roman Hotsiy

Software Engineer, APIs.guru, ReDoc
 

Self-documented APIs: available solutions

Programmers often struggle writing API documentation that is free-form text based. There are several products on the market - like Hypermedia/Hateous, OpenAPI Initiative, and GraphQL - that allow for self-documented API references, but what exactly do they offer us? In his presentation, Roman provides us with several demos and examples, but also lists perks and insufficiencies.
 

Self-documented API documentation as a whole?

The references are only part of the API documentation. As a whole, API documentation could be categorized into:

• Technical details (How to send a request and extract data from the response?) that can be self-documented,
• Conceptual documentation (Why do we need this API?), which cannot be self-documented.

Conclusion: Establish API description formats as a middle ground (write concepts alongside code) and enable developers and tech writers to collaborate according to docs like code.
 

In-between self-documented and written documentation: takeaways

• Reference docs are only part of the API documentation,
• Developers can auto-generate some parts of the API documentation,
• Technical writers are absolutely required to write the other parts,
• Programmers and tech writers should cooperate (check Docs like Code).

Not all Rocket Scientists want to be Brain Surgeons: Lessons Learned Documenting Cryptography APIs

Karen Sawrey

Technical writer at Cossack Labs
 

Cryptography is hard, explaining it is even harder

In her presentation, Karen talks about her job as a technical writer documenting cryptography APIs and the experience she gained, e.g.,

• Keep the balance between exact-scientific and usable,
• Verify continuously,
• Plan: what’s the least number of actions that gives the best results.

Karen describes what the technical team’s workflow looks like, what tools they use, which documentation types they provide, what challenges they face.
 

Master documenting cryptography APIs: tips and tricks

• Nothing is too complicated to explain,
• Choose simple words,
• Think about your documentation users,
• Boldly increase the number of communication channels (get to know your audiences),
• Don’t be afraid to ask questions.

Continuous Swagness for your APIs

Laurent Doguin

Head of Developer Relations at Clever Cloud
 

Continuous integration and delivery

Laurent demo-ed us how they use Swagger to generate a website for their APIs' documentation and specific clients for each language they support. Each time they update the spec they test it, update the website, build, test and deploy the new Clients libraries automatically. He showed us (live demo) how to set everything up from scratch thanks to Jenkins, Artifactory and Clever Cloud.

Laurent’s tips:

• The production has to be perfect,
• There is one process: build, then register, and live without data,
• Keep the more updated version,
• Statelessness is the key: create a factory of instances.

When the Specification Fails: Documenting Inter-Parameter Constraints

Nathalie Oostvogels

PhD student at the Vrije Universiteit Brussel
 

Inter-parameter constraints are common in web API specifications

In web API specifications, constraints come along with parameters. You need to satisfy every constraint for a request to succeed. API specification languages (API Blueprint, RAML, Swagger) and their tools help to ease that process, but do not yet provide a solution to express constraints across parameters (inter-parameter constraints).

Nathalie researched popular web APIs (like Twitter, Google Maps, YouTube, Facebook) and found three types of inter-parameter constraints:

• Exclusive constraints,
• Dependent constraints,
• Group constraints.
   

A new specification language to describe inter-parameter constraints

The speaker shows us how JSON Schema (Swagger/OpenAPI Initiative) features do not allow for an efficient description of inter-parameter constraints.

Nathalie started working on an extension of the OpenAPI Initiative specification language that support inter-parameter constraints. She also recommends the usage of a truth table.

Consequently, documentation tools should be extended:

• render the inter-parameter constraints as a separate block in the docs
• indicate that field is part of inter-parameter constraint

To end, Nathalie provides us with a guide to recognize inter-parameter constraints in API documentation.

Aleksei Akimov - Beyond the Basic Swagger UI: Adyen API Explorer

Aleksei Akimov

Technical writer at Adyen
 

From API to documentation

Adyen’s rapid growth provides challenges concerning documentation. For their API references, they chose the Swagger tool (to implement the OpenAPI specification format - as Aleksei explains the semantic differences). The basic Swagger UI however, the speaker indicates, lacked an effective layout and provides problems with nested structures. How could Adyen go beyond?
 

Reimagining the Swagger UI: from specification to documentation

• One user persona can wear different hats, and act e.g. as the learning developer or the coding developer,
• Work in streams: have team members with different professional profiles,
• Results: Among Adyen’s API Explorer’s first wins are support for multiple specs, adaptive layout, clean structure for nested objects, the multiple code examples.
   

Tips and tricks after building Adyen’s API Explorer

• Let technical writers and developers collaborate on the same content,
• Use the latest version of the OpenAPI,
• Use markdown,
• Integrate swagger in CI,
• OpenAPI supports custom annotations,
• Launch fast and iterate (be agile).

DocOps - Engineering Great Documentation

Adam Butler

Technical Lead of Nexmo Developer
 

DocOps: Engineering to help maintain the documentation

Adam talked about the open-source platform and tools they built when developing Nexmo Developer, for writing rich documentation collaboratively with ease. He talked about how they tackled problems concerning documentation requirements and met their goals.

• How can people contribute on docs while keeping the quality high?
• Think like an engineer: Build tools and processes that give the docs back to the contributing people (engineers, product owners, tech writers, customers, support, …).
   

Nexmo Developer features

• Open source
• Tooling: Ruby + Rails + Nexmo flavoured markdown
• Contribution guides
• Automation
• Docs like Code
   

Read Adam’s article on Extending Markdown with middleware.