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 to where they need in a full developer hub. This is probably 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 in the documentation section. 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 start. Make sure your user knows how to access your API and can learn about what your API/product does. This would be a great place to provide instructions for authentication.
Table of contents are included in your documentation as well, but you might want to turn it on only if you have long documentation pages.
This section is where you will list all your endpoints, the parameters, and any examples you want to provide. 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 it will increase load times significantly.
Generally you want your API reference to be as simple as possible, so that your users can quickly access the information they need. Leave any long instructions or tutorials to the guide section. Example code will be auto-generated for you if you do not have any, but feel free to add your own. It's good to have examples that your reader can just copy and paste! Lastly, make sure you have your API setup 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, just simply import your file and you're good to go! Try to limit the amount of circular references and separate out APIs if your file is extremely large. Each swagger file will import as it's own category. You can read more extensively about our integration here: Swagger/OpenAPI Import.
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 right 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 off 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 anytime. 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 forums so that 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 about a year ago