To help you jumpstart your ReadMe project, we’ve put together some best practices for building and maintaining a top-notch developer hub.

While these are suggestions based on our team’s experience building and using ReadMe, your hub should be tailored to your specific audience since you know what they need better than anyone. Let's dive in!

💫 Creating Your Project

When you first create a new project, it’s a good idea to have your project name, subdomain, and logo ready to go. Upon entering your project’s dashboard, you’ll see an onboarding modal that will guide you through the steps to launching your docs.

📝 All About Documentation

ReadMe offers a few different formats for documentation in your hub: API Reference, Guides, Recipes, Changelog, Discussions, and Landing Page. While you don’t have to take advantage of every section in order to provide a great developer hub and experience, it’s helpful to know each section’s purpose!

API Reference

We recommend getting started with your API reference first. Your API reference not only helps users understand your API, but with ReadMe, it’s where they can try out your API in real time 🕰️

The API reference is where you will list all your endpoints and parameters. Just import your OpenAPI file to get started, or use our manual API editor if you don’t have one. With an extra authentication step, you can pass API keys or other user data to personalize your developers’ experience.

You can add supporting Markdown content below the endpoint content if needed, but we recommend keeping the reference section to just the low-level parameters and examples so that your readers can quickly refer to it.

A highlight of ReadMe’s API Reference format is the Try It playground, which allows users to try your API in realtime and view their request history directly within the reference section of your docs. The Try It button is enabled by default, but if you want to disable it, you’ll need to uncheck the “Enable API Explorer” box in the Additional Options section within the Describe Your API modal window (see below) or insert this code snippet if you’re using the OpenAPI upload option.

OpenAPI Upload

If you are using an OpenAPI definition, we have several syncing options (such as a command line and GitHub integration) and import options (such as file or URL) available! Try to limit the number of circular references, and separate out APIs into separate files if your definition is extremely large. Each OpenAPI file will import as its own category and each endpoint will be its own page. We have extensive information about this integration on our OpenAPI page.

Manual API Editor

While the recommended approach to writing API reference docs is with an OpenAPI file, you can still write beautiful reference documentation using our manual API Editor! Head over to the Manual API Editor guide for the details and best practices.

Guides

Think of Guides as the instruction manual for your API: share tips on what to do first, second, third, authentication details, or more context on what’s possible with your API. We recommend having both Guides and an API reference rather than trying to include everything in the reference section. Keeping these sections separate will allow your users to easily interpret your API and learn more about common use cases for your product.

We recommend creating pages within Guides that help your users understand how your product or API works. A "Getting Started" or some type of introductory section is a good place to begin. This is a great place to provide your users with a high-level overview of what your API/product does and include the relevant details on how to access it.

We also recommend using Guides to house tutorials, in-depth descriptions and schema tables, examples, edge cases, and workflow explainers. For more on Guides, head to this page.

Recipes

Recipes are a great way to walk your users through a common use case with your API. The most effective recipes contain a programming language (or several!) that are commonly used by your users and ideally are documenting a common end-to-end process.

We recommend that your recipes touch on the functionality of multiple endpoints, with steps that explain each endpoint and any associated authentication and parameters. Be sure to embed the recipe in other sections of your documentation so your users can easily find them. Oh, and don't forget the emoji! 🦉

Changelog

ReadMe's built-in Changelog feature allows you to share important updates like new endpoints or breaking API changes directly from your docs. Developers can follow your changelog RSS feed by just adding .rss to the end of your changelog URL (like https://docs.readme.com/main/changelog.rss, for example!).

Learn more about building out your changelog here.

Discussions

We recommend using our Discussions feature like a community discussion forum where your users have a central place to ask each other questions. Think of it as Stack Overflow for your API — if one user asks a question, chances are that other users have the same question!

You can also set up Discussions to function as a simple support system, where your users can ask questions about your product in a public forum. If you are looking for a more robust centralized support system, we recommend customer service software like Zendesk or Intercom. We have third-party integrations for both these products. We also recommend enabling reCaptcha to prevent spam.

Landing Page

Think of the ReadMe’s Landing Page feature as your space to design a welcome mat for your users. A well-designed landing page introduces your audience to your API or product, and is a great starting place for your users to navigate from. This is the page we recommend you customize the most.

If you choose not to have a landing page for your docs, you can choose to direct your users to the first page of your Guides (listed as Documentation) on the site navigation within your project’s dashboard.

🛠 Writing and Editing Workflow

Creating and Editing Pages

Any Project Admin can create, edit, and publish pages. When you create a new page, you’ll see a green toggle bar at the top that defaults to green. This means that when you click the Save button in the top right, the page will automatically be published and go live.

If you want to save your work as you go while keeping the page in draft mode, ensure that the Public/Hidden dropdown is set to Hidden. To see a preview of your page, click the link icon, in the top right next to the Save button, and a new browser window will open to show how your page will render live. You can also share that URL with others who you want to be able to see that page before it's public.

You can also view the page’s history and revert back to a recent version by clicking on the "Page History" button on the righthand side. This is good to use if you make an edit by mistake and want to revert back to an earlier version!

Publishing Content

We have several options for publishing that might work best for your workflow:

• Suggested Edits (this is what we recommend!)
• A Staging environment (Enterprise only)
• Using hidden documentation versions to draft and preview content (this is ideal for larger content migrations, restructuring, etc.)
• Creating a separate project specifically as a sandbox

Managing Versions

If you are maintaining multiple versions of your API or product, you might need multiple versions of your docs as well! In addition to using versions to stage major content changes, you can keep multiple versions of your docs published to give people access to the one they need.

🎨 Appearance

ReadMe has several themes that make it easy to create beautiful documentation for your developers. You'll notice that the color scheme will automatically change based on your logo so that your documentation feels on-brand and personalized to your product.

Custom CSS

If you have more specific requirements for how your documentation looks, you can add your own custom CSS in the Appearance > Custom Stylesheet settings in the dashboard. Above the text box, there’s a Read Best Practices dropdown that we recommend reviewing and employing when writing Custom CSS. We strongly recommend adhering to these best practices so your styles will continue to work as we continuously improve the ReadMe experience. We recommend using our CSS variables as the easiest and safest way to add customization to your docs. We also have theming options available that are specific to the Markdown body of your content—you can find the docs for this here.

📊 All About Developer Dashboard

After building and documenting your API, Developer Dashboard enables you and your team to get real-time information on how and when your developers are actually using it.

Developer Dashboard provides an at-a-glance snapshot of how your API is doing — anything from trends in your API usage to spikes in API errors. It's also where you give logged-in developers instant access to their API keys in your hub so that they can jump right in to making API calls and see responses in real-time. With My Developers, all of your API insights are live right in your project dashboard. From there you can segment info, filter based on API key, email address, and more, and share insights with your team.

Developer Dashboard for Your Team

API analytics help your whole team make more data-driven decisions about your API roadmap and platform strategy. With Developer Dashboard, customer-facing teams can troubleshoot specific errors users are experiencing and provide immediate support. Plus, your team is able to instantly pinpoint a potential issue before it becomes a widespread problem.

Developer Dashboard for Your Developers

Surfacing your developers’ API keys in your hub gives your end developers the tools to make their first API call quickly and seamlessly. Additionally, by providing them with personalized access to their API logs, they can use their most recent activity to quickly debug issues.

Getting Started with Developer Dashboard

Data is only meaningful if it’s actionable, so here are a few ideas for how to get the most from this experience:

• Look at total calls to track API adoption over time and learn which users are using your API the most 🙌
• Compare top endpoints to see which are the most popular and which to prioritize for future improvements 🔊
• Filter by status codes and error rates to quickly diagnose any API errors that you’ll want to communicate to your users ⚠️
• Analyze page views, votes, and comments across your docs to get better visibility into how useful they are for your users 📖