Director of content strategy at Worldpay
Lead API writer at Worldpay
Story continued from 2016 Agile the Docs conference.
Resources and budget from different stakeholders for a proper DX portal
New implementations for DX improvement
Technical details for DX improvement
Global Documentation Manager at KAL
The current situation
Bridget provides us, throughout her talk, with hands-on examples and further references to dive more deeply into the topic of cybersecurity.
Lead Community Engineer at Stoplight
The OpenAPI Specification, a standard, structured approach for describing APIs, can be used for more than writing/generating reference documentation: you can also apply it for e.g. contract testing, prototyping, client SDKs. Taylor explains.
Self-documenting APIs do not exist, there will always be manual work:
Standardization helps, the OpenAPI spec as a collaboration tool:
The OpenAPI spec enhances DX:
Going to infinity: explore further what can be done with the help of OpenAPI, such as linting and style guides.
Senior technical writer at MongoDB
Goal: automate the specification and concentrate talents in developing tutorials. This decision may look obvious in hindsight, but they had to do some research before coming to that conclusion: Writing for Scale: Streamlining API Documentation Maintenance
This talk describes the why and how of automatically generating your API specification.
In every tooling case, automation relies upon creating a YAML configuration file: routes, methods, parameters, error messages, and so on for each endpoint. Each tool provides editors, linters and the like to create and validate these files.
MongoDB chose Swagger: well supported and well adopted. Starting with an existing API with almost 200 endpoints across dozens of classes, there is not full automation to import. Swagger has:
Existing tools to generate the API specification file in six different programming languages With Swagger-Core, the docs team needs only to annotate the existing code (Jersey/JAX-RS for our REST API code).
Tech writer's development environments set up exactly as of their API developers', to enable working with the codebase in a manner consistent with their development practices.
An unexpected benefit of choosing to work within the API codebase: you learn how the code is organized.
For all further technical details –and there is a lot!– look up Anthony's slide deck, with speaker's notes.