This article will go over some of the best practices for building and maintaining your documentation. In the end, it will be up to you how you want to tailor your documentation specifically to your API/product!
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 you can customize the most.
If all you use is the documentation feature though, you can just direct your users to that on the first page in your site navigation.
Generally you want to have a guides section to accompany your reference section. Keeping this separate will allow your user to easily interpret your API or product. The reference section should be kept minimal to just the low-level parameters and examples so that your readers can quickly refer to it.
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 knows how to access your API and learn about what your API/product does. This is also a great place to provide instructions for authentication.
A table of contents is included in your documentation as well, but you might want to turn it on only if you have long documentation pages.
We recommend using the guide section for tutorials, in-depth descriptions and schema tables, examples, edge cases, and workflow explainers.
This section is where you will list all your endpoints and parameters. This section is designed with a single-page architecture, so keep it limited to API reference material. You should not be adding many images or complex widgets to this, otherwise load times will increase significantly.
Generally you want your API reference to be as simple as possible, so your users can quickly access the information they need. Think of this section as a place to simply render your swagger file, or display a reference list of endpoints like an informative encyclopedia or dictionary. We highly recommend putting all long instructions, tutorials, or clarifications in the guide section.
Example code will be auto-generated for you if you don't have any, but feel free to add your own. It's good to have examples that your reader can copy and paste! Lastly, make sure you have your API set up in reference settings and turn on the API Explorer to allow your users to try your API right in the docs.
If you are using OpenAPI, simply import your file and you're 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. You can read more extensively about our integration here: OpenAPI/Swagger Upload.
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 settings icon to revert the page back to a recent version.
Some other features you can use to switch up your workflow include: versioning for a staging environment, or creating a separate project specifically as a sandbox.
ReadMe has been built to make creating beautiful documentation easy, so we have a few themes to choose from. You'll notice that the color scheme will automatically change based on your logo so you can focus on generating great content right away.
If you have more specific requirements for how your docs look, you can add your own custom CSS edits here. However we generally recommend not making any heavy styling changes, since it could affect our core CSS, which can be updated at any time. You should try to stick to font changes and other small styling changes.
This feature is generally used in two ways. The most common way to use it, is as a community discussion forum so your users have a central place to ask each other questions. Think of it as Stack Overflow for your API! You can also use it as a simple support system, where your users can ask you questions. If you are looking for a more robust support system though, you should use something else like Zendesk or Intercom. We have third-party integrations for these products.
Updated 4 months ago