Core Documentation Types
The Documentation Toolkit You Actually Want to Use
ReadMe's core documentation types are designed to create a complete, engaging developer experience that covers all the bases, from "What does this API do?" to "Show me exactly how to implement this specific use case."
Each of out documentation types serves a distinct purpose in your documentation strategy, and together they create a comprehensive resource that helps developers go from curious visitors to power users.
📘 Guides: Your API's Instruction Manual
Guides are the bread and butter of your documentation—the friendly, conversational pages that walk developers through concepts, provide context, and explain the "why" behind your API. They're perfect for:
- Getting started tutorials that help developers make their first API call
- Authentication explanations that guide developers through your security model
- Best practices that show developers how to use your API effectively
- In-depth explanations of complex concepts and workflows
Guides shine when you need to explain concepts in a logical sequence or provide the bigger picture. They're the pages developers read when they're learning about your API for the first time or diving into a new feature.
🔌 API Reference: Your API's Source of Truth
Your API reference is the definitive, interactive catalog of all your endpoints, parameters, and response schemas. Generated from your OpenAPI specification (or created manually), it's where developers go when they need specific technical details about an endpoint.
The API reference is perfect for:
- Exploring available endpoints and their capabilities
- Understanding request and response formats
- Testing API calls directly in the browser
- Finding the exact parameters needed for a specific operation
What makes ReadMe's API reference special is its interactivity—developers can make actual API calls right from your docs, with their own API keys automatically populated.
🧩 Recipes: Your API's Cookbook
While guides explain concepts and the API reference details endpoints, recipes show developers exactly how to accomplish specific tasks using your API. They're the coding equivalent of "watch me do this" tutorials.
Recipes are perfect for:
- Step-by-step walkthroughs of common use cases
- Code examples in multiple programming languages
- Connecting multiple API endpoints to achieve a goal
- Showing real-world implementations of your API
Recipes bridge the gap between understanding your API and actually using it, giving developers concrete examples they can adapt for their own needs.
📰 Changelog: Your API's News Feed
Your API is constantly evolving, and developers need to know what's changed. The changelog is your dedicated space for announcing new features, breaking changes, deprecations, and bug fixes.
A well-maintained changelog:
- Keeps developers informed about changes that might affect their integration
- Highlights new capabilities and documentation they might want to implement
- Shows that your API is actively maintained and improved
- Creates a historical record of your API's evolution
📄 Custom Pages: Your API's Specialty Content
Some content doesn't neatly fit into guides, reference, recipes, or changelogs. That's where custom pages come in—flexible spaces for content that deserves special treatment.
Custom pages are perfect for:
- Creating a standout landing page that introduces your API
- FAQ collections that answer common questions
- Status pages that show system uptime
- Special announcements or promotional content
🏠 Landing Pages: Your API's Front Door
Your landing page is the first impression developers get of your API. This is your chance to showcase what your API can do and guide developers to exactly what they need.
A great landing page:
- Clearly communicates what your API does and why developers should care
- Highlights key features and use cases at a glance
- Provides clear pathways to different sections of your documentation
- Includes prominent call-to-action buttons for getting started
- Sets the tone for your entire developer experience
With ReadMe's landing page editor, you can create a homepage that tells your API's story and get developers excited about what they can build.
Bringing It All Together
The most effective documentation hubs use all these content types in concert, creating a cohesive experience where developers can seamlessly move between conceptual explanations, technical details, practical examples, and up-to-date information about changes.
Ready to create a documentation experience developers will actually enjoy using? Let's start building your documentation hub!
Updated about 23 hours ago