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?
- 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
- Make room for humans: there is room in that machine-readable world for us to be able to inject our skills
- Human-Computer Collaboration:
- When those two are coming together
- 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)
- 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
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
- Look for the spots where you can take advantage of descriptions and can inject your skills into the machine readable aspects
- Look for how you can document more problems, how you can get at those areas that really are human
- Pull that in to create a better and machine-readable developer experience