API THE DOCS, AMSTERDAM 2019 - RECAPS

Two-day conference about API documentation and developer portals. Explore the latest best practices, strategies and new trends.
10-11th October 2019



With great pleasure we share with you the recordings, slide decks and our notes from API The Docs in Amsterdam 2019 October. A big shout-out to the presenters: THANK YOU!

Conference Opening

Kristof Van Tomme

Co-founder and CEO PRONOVIX


"When you start to talk with your peers about subjects that you can influence yourself, and you can have open conversations about all the problems that you are having without having to go on stage... I think it's just magical."

Kristof's Welcome

APIs and our journey to digital ecosystems

Koen Adolfs

Product Owner and API Evangelist at ABN AMRO

"We need to move from an egosystem to an ecosystem. [...] Empower internal and external developers to build the future of banking on top of APIs."

To get there is a couple of marathons.

A/ Cultural and organizational change:you need an API-first mindset and the processes and best practices for the teams in place, where documentation is important.

B/ The APIs must be:

  • Business meaningful
  • Easy to discover
  • Resource based
  • Easy to understand
  • Easy from a consumer perspective
  • Reusable

"How is someone else going to use my service beyond what I can expect that they are going to use it for?"

Complexities:

  • Build consistent APIs
  • Proper technical documentation scaled
  • Manage the API lifecycle
  • Support the users of the APIs
  • When to use APIs, when other technologies?


Koen's opening talk

GitHub as a Landing Page

Lorna Jane Mitchell

Developer advocate at NexmoDev

How and why to bring over your team's docs knowledge to the Github pages.
If users look for docs at the source, aka the code repo, they may never see your devportal.

For this reason, bring the landing page experience into the Github docs. Landing pages bring context to orient users, they should have a similar experience with the Github docs.

Opensourced Nexmo docs standards.

Readme file's content gets rendered on many pages differently and this can be used to advantage.
Every project needs name, purpose, scope, link to docs, license, how to get help.

"More info in a readme is great, your developer audience will find their way through."

Repo types:

  • library Code
  • tool or demo app: make it deployable (docker setup), link to demo or open. Became a pre-sales tool but not trivial to do it.
  • supporting code: not maintained, link back to what it was for, anything else is a bonus
  • docs-as-code is maybe a fourth category

Library Code:

  • pre-requisites, tech requirements, Nexmo account
  • installation instructions: what should the users type to install this thing
  • usage instructions (the API references not sufficient, need lots of examples)

Readme "furniture": use headings and a table of contents to help users navigate longer readme text.

Repo metadata:

  • story based project names
  • description is key because it shows in search results
  • use topics to help indicate both technology and features
  • helps people FIND this with Topic tags, etc.

License field: add exact, opensource approved license. Many people filter search results on license too.

Add contribution guide, code of conduct. In certain situations you do not need contributions: write explicitly what contribution you find useful.
Further reading links.


talk proposal summary

Lorna's slides



Lorna's presentation

Leaping Forward: Finding the Future of Your API Docs

Aaron Verber

DevRel Product Manager at Marqeta

When a good tool doesn't fit your needs anymore.

Marqeta's problem: multiple writers creating and updating lots of docs at the same time in a marketing CMS.

Finding and solving the pain points with existing tools is maybe not enough forever. Scaling may require better tools.

Warning signs may be:

  • Do you create fragile processes to cover tool gaps? Version control, collaboration, and review needs fitting tools.
  • Worry about overwriting others' work?
  • Avoid certain docs because the tool is too difficult?
  • Prefer writing docs outside standard tool?

Track unintended or undesirable outcomes of a tool-change:

  • what friction points come up: survey writer satisfaction
  • measure the impact in terms of overall satisfaction

Can work towards:

  • simple but powerful authoring
  • docs can be closer to code
  • automate
  • portable source
  • consider the ecosystem when choosing

When method searching, go beyond existing pain points:

  • what new things can we do
  • create a shared taxonomy
  • prototype your SSG-toolchain

Then practice:

  • document the tool
  • chat live about problems.
  • demo the ability to solve former pain points together
  • user testing

Marqeta's new toolchain: Gatsby-ASCIIDoc-GitHub-Drone.
Future plan: OpenAPI spec-based toolchain. Pro: automates multiple outputs, singe source of truth. Contra: organizational buy-in required.


talk proposal summary

Aaron's slides



Aaron's presentation

Engineer Stunning API Documentation

Sven Strack

DocOps Engineer at Pronovix

Building, maintaining, continually improve your (API) documentation using docs-as-code the DocOps way.

Test for the quality of documentation! All aspects of API documentation:

  • appealing appearance
  • readable pacing
  • content structure
  • match the audience, does the user find what they are looking for?
  • clarity

Understanding what is good writing. Typo-free doesn’t mean it’s good.

Test first for:

  • grammar (alternative spelling, etc.)
  • SEO
  • accessibility

Using the same tooling for documentation as coding also means:

  • the same code editor for docs writing. Plugins can check for consistency and style guide rules,
  • upload and publish only if the tests pass.

Benefits of docs-as-code setup:

  • help product and dev cycle
  • consistency encourages trust
  • follow defined standards reflecting product and company brand

Learning curve

Need deeper knowledge of engineering tools, workflows, solid base understanding of security.

Tests are working - trust the results.

Developers, devOps, site reliability (SRE) teams help design good tests.

Content strategy and test design:

  • editorial style guidelines
  • markup style guidelines
  • objectives and key results
  • ROT (Redundant, Outdated, Trivial)

Content analytics, automated testing, deploying (publishing)

Write - test- share

Quality Assurance benefits:

  • consistent docs is a trust signal
  • marketing, promotion of product/org
  • customer satisfaction
  • less support work
  • rapid project adoption

Advice:

  • protect your branches
  • validate all your checks according to best practices
  • keep checks “simple” and “easy” to adjust
  • start small
  • make your checks dependent on each other

What you want to achieve:

  • define style guide
  • user stories
  • analytics
  • QA starts locally

Check on accessibility and performance of site over time, always improve (Lighthouse) QA with CI/CD



talk proposal summary

Sven's slides



Sven's presentation

Advacing Your API Strategy in an Infrastructure World

Jaap Brasser

Developer Advocate at Rubrik, Inc.



API landscape challenges:

  • external: APIs relatively novel concept to many, GUI is still more accepted
  • internal: some endpoints are classified

Diverse audience - what are their needs?

1. beginner technical user:

  • simplify API Access (provide modules, SDKs)
  • provide use cases and documentation (samples, quick start guides, video tutorials)

2. experienced technical user:

  • provide access to code (github, code, issues)
  • allow to contribute (clear guidelines, architectural documentation)
  • contact info, social media, GitHub

3. Non-Technical Stakeholder:

  • examples (use-cases, integrations)
  • simplify access (web portal instead of GitHub)
  • GUI design matters

Open-sourced the docs to get feedback, with quick start guides. Unexpected input, also marketing department started using it.

Organized and standardized their GitHub repo:

  • unified labels helped a lot towards contributions
  • standardized ReadMe
  • quick start guides
  • video recordings of initial 1on1 teaching sessions available
  • creation of new repo through Slack was easier to manage

Advice: standardize and automate unit tests to speed up, especially for a very active project.

Future plans:

  • security step-up: no obfuscated code, no external IP addresses
  • multilingual docs: machine translation, need docs separate from code for it


talk proposal summary

Jaap's slides



Jaap's presentation

What Makes an API Product Successful

Anthony Roux

Developer Advocate at AmadeusITGroup



Doubt will cost you potential customers. Be transparent and clear about what you have.

  • open documentation
  • API status page - reduces support requests
  • transparent pricing
  • clear, human readable Terms & conditions
  • make everything easy to access

It has to take less than a minute's reading to understand what is your core business.
Make the references interactive, parameters can be set ready for copy-and-paste, keep always up to date.

Onboarding: easy and fast!

Sign-up is only for tryout, you can ask questions later. Rule of thumb advice: 30 seconds to understand your API, 0 seconds to create an account and 3 minutes to first API call.
A later email validation should give valuable information: hand-holding and inspiration.

Examples/Demos:

  • template examples make life easier
  • show what existing customers are doing, success stories: positive acknowledgment to existing users and inspiration for new users
  • code samples
  • SDKs can be both generated and handmade

You can easily give a free trial with a limited test data set.

Payment: as you go, transparent model with alternative paths.
Support: clear support channels, public platform for techies, FAQ. Set up monitoring.
Summary: make it easy, be transparent and focus on DX. Hire a devrel.


talk proposal summary

Anthony's slides



Anthony's presentation

Bulletproofing Your APIs: Why Users' Feedback Matters

Maria Garcia

Strategy, Program Manager at Amadeus for Developers



User feedback is absolutely instrumental in getting to a great DX:

  • shows your blind spots
  • you must build a strong product roadmap
  • validate your business model by talking to potential customers, how can you support them best and discover new monetization opportunities

User interviews: uncover common needs and frustrations. Target customers, scripted, no leading questions.

Prototyping: move from concept to building, fix bugs early on.

Usability tests to observe how people use your APIs:

  • define scope and tasks
  • 5 testers minimum, usually 85% issues found
  • think aloud, screenshare, webcam!
  • observe, listen and record
  • give incentives (e.g. vouchers)

Goal: how to make your docs easy to find and easy to use, the first API call fast.

Index cards on taxonomy: validate your assumptions on associations.

Beta-testing is the moment of truth. Production ready apps, in-depth review, inconsistencies and performance issues found. Can be a small internal & external audience. It is a lot of effort to create and maintain a beta-testers' community. Always have the technical resources available for what you are promising.

Survey, metrics, support: ascertain the health of your APIs.

Open support channels: 75% of users would report issues if there is a channel.

Hackathons: direct observation options, answer support questions, team interviews, surveys. Follow-up with participants and beta-testers can bring the true deep insights.

Customers' frustrations are your compass.



talk proposal summary

Maria's slides



Maria's presentation

Business Integration Made Easy with APIs

Mark Simpson

Director at Griffiths Waite

Alexandra Stramarko

Product Owner at Atradius

The Atradius API Portal details can unfortunately only be shared to the wider public once the portal is formally released. It is currently in beta. Release was originally scheduled for September '19 but the launch was postponed to November '19. Atradius emailed their apologies for not being able to share publicly.


talk proposal summary

An Inside Look at a Large-scale Writer-driven REST API Doc Solution at Salesforce

Kelsey Lambert

Lead Technical Writer at Salesforce

Sejal Parikh

Product Owner at Salesforce



Currently 23+ REST APIs, 10 authoring tool chains, 175+ writers, 10 doc portals.

Challenges: multi-version support, localization, differing release schedules, limited codebase access for so many writers. Hundreds of scrum teams.

Need: a spec-agnostic authoring and publishing solution that fits 175+ writers, minimize context-switch.

Agreed Goal: unified automation pipeline for engineers, simple process and toolchain for writers, 1 amazing API portal for customers.

Changes for productivity started as grassroots efforts from writers:

  • do background research while waiting for budget/support
  • catalogued all APIs across organization, identify problems and prove the hypothesis
  • create new style guide then spec on top of OpenAPI
  • start training other writers to use it, create an example
  • shared ownership of requirements across teams mapped
  • get support within the whole organization
  • API governance and strategy meetings: have a documentarian participate

Friends of docs:

  1. engineering teams generate API spec from code

  2. writers and DocOps update docs

  3. developer marketing team publishes the docs to a customer portal

Results in one round proposal for change: 1. high-level requirements + 2. technical proposal + 3. user-stories

Obstacles to mind:

  • lots of teams trying to improve -- partner with teams with similar issues
  • align the stakeholders by facilitating face-to-face meetings -- this was surprisingly welcome
  • track down the answers yourself
  • secure the funding

Separate out the docs from the API spec file by a parser, so updates are easier for writers. Notifications for writers about new tickets for writing needs automated.



talk proposal summary

Kelsey and Sejal's slides



Kelsey and Sejal's presentation

Effective API Governance: Lessons Learnt

Alvaro Navarro

Developer Advocate at AmadeusITGroup



Why do you need API governance? Because of the massive amount of information moving.
Lots of different people designing and maintaining APIs in the company.

Regulation is necessary to keep these APIs reliable.

API governance within Amadeus is:

  • community of API designers and developers
  • ownership of guidelines, of data dictionaries and of processes
  • support

Amadeus' HAPPY principle:

  • Homogeneous (all APIs should look the same, style and documentation)
  • Active (comment, decide, be actively contribute)
  • Pragmatic (think about the API consumer not yourself)
  • Positive (give opinion to someone, be constructive criticism)
  • Young (hungry to learn new tech and tools)

Responsibilities/purpose:

  • decision logs on technical discussions to share knowledge and ideas
  • review API submissions: follow a standard template

API template fields:

  • use case
  • flows (how to use the API)
  • data dictionary
  • URI
  • examples
  • swagger specs

Phases of API creation and review:

  • designer
  • under construction (1 to 4 weeks)
  • in progress to pending (1 week review process)
  • validated when true: 1. validated review card 2. documentation 3. swagger



talk proposal summary

Alvaro's slides



Alvaro's presentation

API Descriptions as Production Code

Phil Sturgeon

Architect at Stoplight.io



What tooling supports Open API v3.0?

Design first or code first?

Options:

  1. code first, generate docs: slow feedback loop, customer feedback comes after the docs (putting docs in with code, theoretically mostly right and evolving)

  2. design first, ditch for code first

  3. design first, evolve with code: design with OpenAPI, mocks and docs, get customer feedback. Use open API files to simplify code, deploy code and docs. New functionality requested: repeat.

Stoplight developed an editor to work well writing APIs. How/when do we create documentation? Create mocks? Their solution is Studio

Keep code and docs in sync: rendering of description files, use them to simplify the code, involve the developers in this.

Validation, tests:

  • server-side validation
  • Ruby validation, javascript validation
  • multiple sources of truth = checking for lies
  • Dredd is great but takes a lot of work and after a while teams tend to disable it
  • with OpenAPI you can implement midware to validate every single endpoint.
  • a standard error-format will give consistent error messages.
  • the description doc should say what the rules are and the API and the references adhere to that truth
  • request validation at gateway, validate payloads before application server is called

Enforcing style guides.
Consistent APIs save you time and money.



talk proposal summary

Phil's slides



Phil's presentation

How to Embed UX Thinking in Your Next API

Steph Shin

Product Designer at Shopify



How do users understand the problem space?

Discussions can be difficult because words often hold many different definitions. Diagrams, models or a glossary could help ensure a better alignment.

In analyzing past decisions and other companies' decisions, you must consider the context of these decisions. The context may have changed since then.

When interviewing: no leading questions!

Use visual representations to map out your concept in a complex ecosystem.

Tree-testing is a good way to check a GraphQL schema with users. Eg. it showed that the logic Shopify devs thought of was working, but also showed that users found another route to the same answer.

Oversimplification can ultimately complicate things! Avoid conflating similar but separate concepts, it could cause problems when scaling.

To avoid lengthy debates on terminology you can create a glossary and work on the logic, agree to work out the precise terminology later. Because naming things is hard.

Balance between your product vision and users' feedback.


talk proposal summary

Steph's slides



Steph's presentation

Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0

Conference sponsors:

AbnAmro Manning BuildKite Pronovix