Best Practices

This article will go over several best practices for building and maintaining beautiful documentation with ReadMe. Note that while these are suggestions based on our experience building and using ReadMe docs, your documentation should be tailored to your specific audience — you know what they need better than anyone. Let's dive in!

👋 Landing Page

A well-designed landing page will be a good starting place for your users to navigate from in a full developer hub. This is the page we recommend you customize the most.

If you're only using the Guides (also known as Documentation) feature, you can just direct your users to that on the first page in your site navigation.

📝 Documentation

Generally you want to have a Guides section to accompany your API Reference section. Keeping this separate will allow your user to easily interpret your API and learn more about common use cases for your product. The reference section should be confined to just the low-level parameters and examples so that your readers can quickly refer to it.

Guides

Use this section to get your user primed to consume your product or API. A Getting Started section would be a good place to begin. Make sure your user learns about what your API/product does and knows how to access it.

We recommend using the guide section for tutorials, in-depth descriptions and schema tables, examples, edge cases, and workflow explainers.

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! 🦉

API Reference

This is where you will list all your endpoints and parameters with either an OpenAPI file or an API definition written with our Manual API editor. You can add supporting markdown content below the endpoint content if needed.

We encourage you to enable the API Explorer (enabled by default), which allows your users to try your API and view their request history directly within the docs.

OpenAPI (Swagger)

If you are using an OpenAPI file, simply import it and you should be good to go! Try to limit the number of circular references, and separate out APIs if your file 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, the specification can be confusing and these files can be difficult to maintain. 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.

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 url of your changelog (like https://docs.readme.com/changelog.rss for example!). Some customers also embed a support widget or email subscription box to let developers get help quickly or sign up for email updates.

Discussions

The recommended approach to using support forums is as 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! We also recommend enabling reCaptcha to prevent spam.

You can also use it 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.

🛠 Content Workflow

Anytime you create a page, it will be unlisted by default. Click on the dropdown next to the save button to publish it when you are ready. Any admin user has the ability to edit and publish pages. If an edit is made by mistake, no worries! Click on the "Page History" button on the righthand side to view the previous page history and revert the page back to a recent 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. You'll notice that the color scheme will automatically change based on your logo so you can focus on generating great content right away.

Custom CSS

If you have more specific requirements for how your docs look, you can add your own custom CSS in the Appearance > Custom Stylesheet settings in the dashboard. Above the text box, you'll see a list of best practices that we recommend using 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. The recommended approach to CSS is by using our CSS variables—this is 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.


Did this page help you?