API Documentation and Help Docs: Can They Live Together?

Great documentation can make the difference between a good and a bad user experience. With many different types of documentation, it can be difficult to keep things organized. Your API requires a reference, guides, and other content to help developers. The product your API supports may need its own reference material, including screenshots and videos. Whether these different types of documentation coexist in one place or have separate sites will depend on who you expect to use each of them.

In this post, we’ll outline what you need for holistic API documentation. Then we’ll see whether product help docs should be included. Finally, we’ll look at the tooling required if API documentation and help docs can truly live together.

Many Different Types of API Docs

When you think of API documentation, do you imagine a list of endpoints and fields? While important, you could be missing other types of API docs. At the same time, you might be limiting your reference, as well.

Let’s look at what API docs you should have in most cases:

• A complete, accurate API reference (harder than it seems)
• A quick start guide to get developers up to speed
• Situational guides aimed at specific use cases
• Example applications or code samples

That may seem like a lot, but they go a long way to saving developer time. Among one of the biggest headaches is an inaccurate—or outdated—API reference. OpenAPI documents should make this time sink a thing of the past. You can use Stoplight Studio to both create OpenAPI definitions and generate an API reference any time the API changes. You should include request data, response examples, and error codes in your reference, as they can also be generated from your OpenAPI document.

You’ll want your API reference to live alongside your other documentation, which provides additional context for developers. Much like a cookbook is more than a collection of ingredients, thorough API documentation should be more than a collection of endpoints. And just how cookbooks instruct chefs how to make dishes, API documentation should show developers how to complete common tasks using your API.

That’s where a great Getting Started Guide can point developers down the right path by providing an example, demonstrating how to set up their environment, and then showing how to quickly complete an API call. In addition, you can create situational guides and even complete applications. Host these alongside your API reference, because developers will want to use them together. Stoplight Studio works with both Markdown and OpenAPI documents to help you produce these different types of documentation in one place.

But what about the non-API documentation? Your product or service also needs its own help documentation, which can’t be generated like a reference. Should it live alongside other situational guides?

Consider Your Help Doc Audience

Your help docs aid people using your service. They log into your site and view a dashboard, or download and install it on their machines. Similar to using your API, they’ll have problems to fix or tasks to accomplish. Your help docs allow them a self-serve experience (and save your support team from answering the same questions over and over). How you structure your help documentation and API documentation is greatly dependent on your audience.

In general, consider the following:

• If your service is for developers, it makes sense to serve both your API and help docs from the same place.
• If your service is not for developers, it may be best to keep your API and help docs separated.

Consider the analogy of a copy machine. The manual for using the machine—setting up paper trays, making copies, and even removing jams—is not the same one the repair company uses. If developers aren’t the users of your service, you don’t want to overwhelm them with technical documentation. Or worse, you don’t want them to think they’re in the wrong place.

By contrast, a service aimed at developers will want all the information logically organized together, ensuring developers don’t have to jump around multiple spots searching for what they need.

Oftentimes, this delineation isn’t so straightforward. In many companies, such as tech startups, those in non-developer roles may have to occasionally wade into the developer’s domain of API documentation. In cases like these, it may still be prudent to keep them separate, but easily transitionable to one another. In this case, the Getting Started Guide is all the more important as a friendly introduction to the intimidating realm of APIs. Ultimately, it’s a judgment call, and as you know your service best, it’s yours to make.

One final consideration is which teams will be maintaining your documentation, whether API or help docs. These often diverge based on the intended audience as well, due to the job functions that support them.

Tooling Requirements for Documentation

It’s natural to want a single tool for all types of documentation. However, with any choice you make, you’re also choosing an interface for the team that must support it.

Consider your API documentation, which often requires collaboration with your engineering team. Shoehorning API docs into a help docs platform likely won’t work. Your engineering team lives in version control, such as Git, so a manual process to even copy-paste into a CMS won’t get done. As engineering makes changes to your API, your documentation needs to change with it. Generating your API reference will be sure to prevent a lot of potential headaches down the line.

To keep additional API docs (such as the Getting Started Guide) alongside your reference, you’ll want to use developer-friendly formats like Markdown, which allows rich content such as linking and images. In addition, Markdown files can be stored in version control, allowing engineers to track changes and ensure updates.

The downside is these interfaces might not be as welcoming to team members who aren’t pushing code daily. The teams working on help docs for your service may expect a CMS frontend and other tools expected in non-developer tooling. For this reason, it might make more sense to keep your help docs separate from your API docs.

For engineering-focused organizations, including those wanting to support their teams with great internal documentation, an OpenAPI and Markdown approach makes the most sense. You can include many different types of documentation to help your technical users find solutions quickly.

Stoplight Studio, Stoplight’s free OpenAPI editor, allows you to integrate your API with Git, as well as generate an API reference from your most recent OpenAPI document. You can even include all your other documentation as Markdown. And it even goes beyond API design and documentation, with style guides and mock servers built-in. Try Stoplight Studio today.