Understanding API Documentation

Estimated reading time: 11-12 minutes

Last year, in 2024, I started learning about (REST) API documentation partly out of pure curiosity, partly as a way to extend my technical writing knowledge. I completed the I'd Rather Be Writing - API doc course in both its written and youtube video series formats, then dove directly into the OpenAPI specification. But I still felt that something was missing: the coding part! So I jumped to learn the basics of API coding in Python, enough to build a conceptual bridge between API documentation theory, OpenAPI specification, and actual code. It was enlightening to finally connect core API concepts (endpoints, methods, requests/responses, data schemas, HTTP error codes) with real code, specifications, and documentation.

Still, the division of API documentation into "conceptual" and "reference" documentation remained confusing to me. Reference documentation made sense—it's the comprehensive content for deeper system integration. But why call the practical, enablement-focused sections "conceptual"? Why not "Hands-on documentation" or "Enablement documentation"?

Looking at real API docs from various companies helped me realize that beyond reference documentation, companies give different names to their API documentation sections and offer getting started guides and tutorials—the truly practical stuff.

Now that I'm reviewing my own API documentation samples, I decided to share the framework that helped me connect theory with practice. It cleared up my confusion and gave me a better way to think about API documentation structure. I hope you find it helpful too.