APIDAYS PARIS 2019: API the Docs Track

A track that focuses on the latest best practices, strategies and new trends relevant to API documentation and developer portals
10th December 2019



With great pleasure, we share with you the recordings, presentation slides and our recaps from APIdays, API The Docs Track in Paris 2019 December. A big Thank you to all the speakers!

Increasing API Adoption via a Code PlayGround

S. Adeel Ali

Founder & CEO at APIMatic.io

How many developers are using your developer portal?

If the answer is an awkward silence, maybe it is because the developer needs to write code before they can create their first ‘Hello World’ using the API.

Today, developers are the connection between APIs and the outside world where APIs are independent mediums between platform- and language-specific devices.

You need to treat APIs as a product, and if you do so, care for the user (developer) experience. Make the developer achieve her/his goal in the least number of steps and amount of time.

How can you help them access and use your APIs more easily?

  • Don’t make them code (anything extra).

    • Provide a Getting started guide: developers need to know everything that is specific to your APIs (For example: how can they have access to the sandbox, how can they make requests? What are the errors and data types?)
    • Include Dynamic code samples: make it interactive, use checkboxes - consider it as a playground, don’t make it difficult. Generate code samples.
    • Have Assisted authentication available: keep it as simple as possible.
    • Maintain SDKs / Client Libraries: provide a download button, make it possible to create a complete file from the generated code and let the developers try it out with their own inputs and settings.

  • Let them focus on what they are building.

  • Know your audience: speak their (programming) language(s).



talk proposal summary

Ali's slides



Ali's presentation

API SDK Development - Lessons Learned

Jaap Brasser

Developer Advocate at Rubrik Inc.

Backup is traditionally not an innovative space because of legacy tooling or custom tools/modules.

The goal of building the SDKs:

Simplify the API interaction:

  • Target different kinds of users not only developers.
  • Structured output: to be able to use the JSON output in a more intuitive way.
  • No direct API calls: APIs/endpoints should be provided in different SDKs so they can consume the resources without having to worry if anything changes.
  • Session management: end users should be provided the ability to be able to connect to multiple instances at the same time.

Interactive use: Supporting multiple languages, simplified and more human-readable data output.

Extensibility: Ease of updating, Build tooling on SDK, Extend SDK based on the requirements of the tools with the help of a feedback loop.

Additional goals: SDKs are Open source, Unit tests, Documentation.

Challenges:

  • Team enablement: make sure everyone in the team knows how to contribute
  • OpenSource management: establish how the development process can be automated
  • Bugs in APIs: improve APIs based on the development have been on the SDKs
  • New API version: make sure that new features and functionalities are integrated

Lessons learned:

  1. Create coding and contribution standards
  2. Enforce unit tests
  3. Enable the contributors
  4. Integrations and tooling improvements
  5. Separate time for issues and contributions
  6. Do not automate everything



talk proposal summary

Jaap's slides



Jaap's presentation

Designing APIs for Humans: Leveraging UX Methods For Develop Human Centered APIs

Julia Elman

UX Lead at Ad Hoc LLC

If an API design considers the needs of developers (DX) and focuses on engineering aspects and technical needs only, it has zero connection to end users. This leads to a cycle of creating data that only suits the needs of the task at hand.

“We should strive to end users’ needs to be able to build data-rich applications that serve end user needs alongside the business requirements.”

Human-centered design (HCD) focuses on the overall usability of the product and accessibility for a particular userbase (personas). The most important metric to measure the success of an API program is usage.

How problem-solving is done with the HCD Life Cycle:

  • Define: loosely defined hypothesis which includes goals and outcomes.
  • Discover: get to know the needs and pain-points of users.
  • Build: creating testable outcomes.
  • Validate test the solution with users to build the best possible product.

HCD provides a new concept and way of working that will get designers and developers closer to the data and the interfaces that interact with the data.

Use API data and architecture in the process:

Human-centered design identifies what information the end user will look for when using the application. With this knowledge, APIs can be built to convey the most relevant data.



talk proposal summary

Julia's slides



Julia's presentation

Scaling API Docs: A Role for Developer Portals in Digital Transformation

Kristof Van Tomme

Co-Founder & CEO at Pronovix

Can we combine biotechnology and devportals/digital transformation?

What is digital transformation aside from being a buzzword?

Enterprise companies are adaptive and rigid. To become more adaptive, we need more learning surface with customers.

One goal, many transformations: Agile transformation, DevOps, Self-organizing teams, InnerSourcing, APIs.

Digital transformation is changing the architecture of the world and of how business works. It has increased our interconnection and interdependence.

Two major results:

  • The value space singularity: proximity is replaced by experience - it’s not important how close you live to your customer but how fast you deliver.
  • Increasing complexity of the world around us: complex environments necessitate complex agents. It is crucial to be able to change behavior on the fly.

“Through your developer community a devportal can help you tune your company for complex adaptive behavior.”

Patterns for complex adaptivity: 5 properties of adjustment to become a complex adaptive system (CAS).

  1. Cooperate to remove friction: build APIs with good DX, talk to the developers who use your APIs, adjustment costs can’t be avoided.
  2. Interconnectedness: increase interconnection through APIs by building as few developer portals as possible and encouraging reuse.
  3. Interdependence: create loosely coupled interdependence through APIs. API consumers should be able to influence API design but not dictating it.
  4. Diversity: internal diversity should be available for the whole organization, while outside the company API partnership platforms enable getting in touch with other organizations.
  5. Adaptivity: use APIs as the boundary behind which teams can adapt.



talk proposal summary
blog post

Kristof's slides



Kristof's presentation

Six Principles of the Next Generation Developer Portal

Mike Budzynski

Product Manager at Microsoft Azure API Management

The first step when building developer portals for customers is to conduct extensive research to plan and design before development.

The 6 principles that lead technical decisions:

  1. Architect for effortless scalability: make sure that the developer portal is able to serve plenty of visitors without consuming too many resources of the API management program. For example, the Lightweight JAMstack architecture.
  2. Allow extensibility: allow the customer to extend their own developer portal. Component-based architecture and OpenSource codebase can help with this.
  3. Enable easy deployments anywhere: JAMstack technology requires a static site generation step. Being OpenSource means access to open tools that you can run by yourself.
  4. Accelerate go-to-market: customers can go to the market as soon as possible. A default content (set of features) that is carefully crafted to follow the latest design trends, has an accessible interface, cross-device compatibility, and clear structure helps the process.
  5. Tailor to administrators, content editors, designers, and developers: developer portals are used by two main circles: API providers and Consumers. Use role-based access for administrators, drag and drop visual editor for content editors, styling guide panel for designers, and API reference, console, easy navigation for developers.
  6. Embrace DevOps: it helps to migrate multiple environments, perform backups or restore it, enable certain setup processes for the changes: REST APIs, providing scripts for migration and backups, source control.



talk proposal summary

Mike's slides



Mike's presentation

Lessons Learned From Rebuilding a Developer Documentation Website

Ilona Koren-Deutsch

Technical Documentation Manager at Twitch

Prabhjot Singh

Software Developer at Twitch

Needs Analysis:

“If your API is the product, the documentation is the user interface.”

Identify what makes good documentation and make sure that everything is available and searchable.

Issues with the current documentation:

  • Difficult CMS that is hard for the technical writers to manipulate.
  • It consumes an enormous amount of engineering time to fix its constant breaking.
  • Complicated interaction with CircleCI.
  • Code that developers can’t copy-and-paste.
  • Feedback comes from too many places (e.g. Dev forum, Discord, informal feedback)

Taking a design-first documentation approach, OpenAPI can solve our problems as it allows you to describe your entire API (endpoints, operation parameters, authentication, contact information).

Planning to use OpenAPI for the Twitch APIs encourages developers and tech writers to work together.

Tools: We go from OpenAPI Spec through a translator that transforms the docs to be digestible.

Demo Results:

The generated documentation provides:

  • APIs organized by tags
  • manual sorting to provide a consistent system of organized endpoints
  • the ability to add links, changelog, or friendly content, like Introduction.
  • authentication information
  • sample responses
  • search bar and navigation



talk proposal summary

Ilona and Prabhjot's slides



Ilona and Prabhjot's presentation

They forced you to make documentation... save yourself with automated compliance

Vlad Stirbu

Founder at CompliancePal

What happens when agile development meets with regulated environments?

Medical software documentation has to comply with:

  • a variety of regulations,
  • different regional or governmental legislations,
  • ISO technical standards.

Modern agile development is based on 2-4 week long sprints. By the end of this period the development team ships a fully functional product.

Where does the documentation fit in?

Typically, the development phase is followed by a documentation phase where the now fixed configurations are documented for different audiences. Deployment can happen once this is done.

In reality, if the documentation has to change as frequently as the code, you need an automatic method to keep the documentation always up-to-date.

You can use an augmented GitHub workflow that makes it possible for developers and for compliance officers to achieve a continuous seamless experience through APIs. You must start using this method from the beginning of the development, and do it with each commit.

Find the real use of documentation. And do it for real, not by obligation.



Vlad's slides



Vlad's presentation

A Balanced Diet of Documentation

Nathaniel Okenwa

Developer Evangelist at Twilio Inc.

To support the developers effective use of your APIs you need to equip them with the information they need. Documentation is one of the ways to achieve this goal.

Try to balance different kinds of documentation types for maximized impact.

Never forget: people will use or not use your products based on their experience.

Focus on answering these questions:

  • Why are our developers using our documentation?
  • Do they want to learn new technology, do they need to solve a problem to move forward, or have they just forgot something?

Address your documentation to each of them: use variety and balance.

Documentation pyramid:

  • Minimum Viable Documentation:
    • Reference manuals
    • Quickstart
    • Tutorials, Guides, and Samples
  • Key Pillars:
    • FAQs
    • API Explorer
    • Communication Channels
  • Engaging Offerings:
    • Developer Blog
    • Video content
  • “Cherries on top”: Fun

Personalize your documentation to your audience. You have to take measures to decide what you should focus on:

  • Blind Testing
  • Website Analytics
  • Collect Feedback
  • Monitor Support Requests



talk proposal summary

Nathaniel's slides



Nathaniel's presentation

Continuous Documentation - The best time is now

Kenigbolo Meya Stephen

Front-end Engineer Lead at BCaster
Arch Conveyer/Community Manager at Code Afrique

Continuous documentation

A documentation pattern that takes into consideration the constant changes/improvements in code and business logic needs to be reflected internally for every closed sprint.

If your documentation is unable to catch-up with the changes, you’ll achieve an unsynchronized knowledge-base.

You have to communicate with someone you don't know. If you cannot pass information to users, your documentation is not communicating.

Do your developers write the documentation? Do you have a dedicated team for that? How do you handle your documentation?

What should you improve?

  • Readmes:
    • Ensure Markdown.
    • Keep them short. If a “Readme” has more than three sections, there is information that needs to be somewhere else.
    • Link separate MD files together.
  • Avoid unhelpful phrases:
    • Define, then spot them using a word checker.
    • Write to everyone, don’t assume the technical knowledge of the users.
    • Call a non-technical person to help you review.
  • Avoid inconsiderate writing:
    • Gender favouring
    • Race-related phrases
    • Polarizing/Unequal phrases
  • Review your documentation from time-to-time just as rigorously as you review your code.
  • Treat your documentation quality better than you treat code quality.

Share your useful practices with the community.



talk proposal summary

Kenigbolo's slides



Kenigbolo's presentation

Conference sponsors:

APIdays Pronovix