Adam DuVander - Machine-readable Developer Experience

All aspects of a developer’s interaction with a company, its service, and its products. How can we make these interactions better for a developer audience?

1. Developer Experience:
   • Make room for machines: where can we allow some into the world of DX?
   • Automating the pieces that are repetitive so humans can focus on the areas where they can add the most
2. Machine-readable:
   • Make room for humans: there is room in that machine-readable world for us to be able to inject our skills
3. Human-Computer Collaboration:
   • When those two are coming together

About OpenAPI

• Description can be list of endpoints or even use cases
• There is no direct connection between what a machine sees and what a developer sees
• Machine-readable DX is about to know where we can pull in machines and where we are more likely able to focus our skills
• Making sure that the documentation is always updated along with the OpenAPI is a part where we can help to improve DX
• Use tools to do that (http://openapi.tools)

Experiencing APIs:

• SDKs
  • You can build client libraries from OpenAPI and other descriptions
  • The API is often experienced through those libraries
  • Client library matrix helps to understand what they do and don’t support
• Try an API within the docs
  • Interactive documentation
  • With API explorer or some kind of try-out functionality to be able to experience that API before you go out to the SDKs or to code to be able to use it
• Try an API before its coded
  • For internal developers or alpha testers
  • Taking that machine-readable piece and creating mock servers (local or hosted somewhere)
  • Being able to have a good experience even though you don’t yet have an API

Documenting APIs

Even though OpenAPIs are absolutely machine-readable, there is plenty of room for people to add human-readable aspects to an OpenAPI description and to make sure what gets generated isn’t bad docs.

• Include good example responses
  • Add example and description to the fields and give them names = injecting human skills into what is otherwise a machine description
• Encourage consistency
  • Within an API and across APIs
  • Use tools, like linters to:
    • Create rules to make sure that all fields follow the same style/design
    • Helps to find the inconsistencies
• Confirm accuracy
  • How does the description actually get updated? Hopefully as part of an engineering process
  • Does what you have in your documentation matches the actual API description?
  • Where is it placed on the spectrum of engineering and technical writing? Somewhere in between the two, where adding a little bit of technology will make a better developer experience

All these aspects are really about Human-Computer collaboration.

Focus on greater experiences

1. Getting starting guide

• To make sure that some gets started on the right foot
• Room for humans: humans can set the context
  • You can find ways to codify that
• Getting started doc + github repo + automatic deploy
• Everywhere you look and add the context, there is a way to be able to add some machine readable aspects

2. Use cases

• Humans define the use cases
• How can you turn that into something that remembers what that use case is?
• For example, a series of API calls that are required to cover a specific use case
• By being able to encapsulate those and write about them in a human way, you can help someone import that into a project

3. Problem solution

• Help, educate, inspire people to solve the problems that developers might encounter
• Humans understand the problem
• Tutorials: context + the code that goes along are be able to help someone with that actual solution

Summary

1. Look for the spots where you can take advantage of descriptions and can inject your skills into the machine readable aspects
2. Look for how you can document more problems, how you can get at those areas that really are human
3. Pull that in to create a better and machine-readable developer experience