API documentation for a weather API

Context

OpenWeather’s Current Weather Data API is a valuable resource for developers, but its documentation could be improved.

My role

My goal was to revamp the documentation to help developers integrate the API quickly and effectively.

Process

1. Exploring the API: I created an account and tested the API using Postman to gain a deep understanding of its capabilities and limitations.

2. Taking a developer-centric approach: while testing the API, I focused on the onboarding process and learning experience for developers.

3. Analyzing the existing documentation: I identified ways to improve navigation, usability, and the developer experience.

4. Building the content:

   • I created an OpenAPI definition that describes the API.
   • I used Mintlify to generate the API reference documentation and an interactive playground.
   • I created a getting started guide and pages about the API, rate limits, and authentication methods.

Results

• A getting started guide walks developers through making their first API call, reducing the onboarding time.
• An interactive playground enables developers to make API calls directly within the documentation.

Takeaways

• Walking in the developer’s shoes was crucial for identifying areas for improvement.
• Choosing the right tools streamlined the documentation process and made it more interactive.