June 2024 Summaries

Git workflows offer numerous benefits for technical writers working on API documentation, including version control, collaboration, and automation. However, challenges arise when dealing with code-generated docs, such as overly technical language or incomplete information. To improve the workflow, consider merging improved copy into the source, using code annotations for one-time generation, or employing OpenAPI specification overlays. For greenfield API design, collaboration is key, and involving technical writers early on can lead to better documentation that aligns with the broader goals of the API program. Storing API documentation in a separate git repository can provide flexibility in management, version control for changes, and easier collaboration across teams. Automation tools and diff tooling can further streamline this process.

The article discusses the importance of discoverability for APIs and introduces APIs.json as a solution. APIs.json is a specification that aims to solve API discoverability, created by Kin "API Evangelist" Lane and Steven Willmott. It contains two simple concepts: a "Well Known" URL of /apis.json or /apis.yaml, and a specific JSON/YAML data format for that URL. The APIs.json file helps software find your APIs and learn about them by providing metadata about the collection of APIs and an array of APIs with their respective details. Bump.sh automatically creates an /apis.json for anyone using Documentation Hubs, which can be used to submit APIs to API marketplaces like APIs.io. Other potential uses for APIs.json include quality assurance on developer portals and monitoring by advertising health endpoints of APIs.