Context
OpenWeather provides a widely used API for current weather data. The existing documentation contained all required information, but made it difficult for developers to understand how to make a first successful request.
Problem
The documentation made first-time integration harder than necessary:
- No clear path to a first API call
- Authentication and rate limits were documented but not contextualized
- Examples were inconsistent and not tied to real tasks
Developers had to piece together information across multiple pages before getting a working request.
My role
Improved API onboarding by creating a clear path to first API call, using an OpenAPI-based reference and task-focused quickstart.
Approach
- Tested the API as a new user to map the onboarding flow
- Identified missing steps and unclear concepts in the existing docs
- Introduced an OpenAPI-based reference for consistency
- Designed a quickstart focused on reaching a first successful API call
Key decisions
- Prioritized a quickstart over expanding existing reference content
- Used OpenAPI to enforce consistency across endpoints and examples
- Separated conceptual explanations (auth, rate limits) from task-based flows
- Added an interactive playground to reduce context switching
What changed
- Developers can make a first API call from a single entry point
- Reference documentation is generated from a consistent OpenAPI source
- Examples are aligned with real usage instead of isolated snippets
Evidence
This was a portfolio rewrite, so no internal product metrics were available. Evidence is based on observable documentation changes:
- Reduced number of steps and pages needed to reach a working first API request
- Clearer mapping between tasks and documentation sections
- Direct endpoint testing through the interactive playground
Takeaways
- Most friction came from structure, not missing content
- A clear onboarding path is more valuable than exhaustive documentation
- Consistency (via OpenAPI) reduces long-term maintenance and confusion