Designing and writing good API documentation can be a daunting task, but is critical for any API-driven or B2D (Business 2 Developer) company to ensure developer success. Your documentation is also your company’s marketing asset and may be the first few pages a new prospect visits to assess how difficult your integration is and how the product works.

To help improve how your API documentation is presented, in this post, we’ll analyze different ways to improve your developer center structure so that it caters nicely to your specific visitors. An important facet of this is choosing the best type of site architecture for your API developer portal.

High Level Organization

Before discussing specific documentation features, it’s worthwhile to discuss the high level organization of the documentation. Each company will have specific requirements for docs, but amongst API-first companies, documentation typically falls into one of three categories:

1. Centralized docs with separate API reference
2. Centralized docs combined with API reference
3. Decentralized docs

1. Centralized docs with separate API reference

Companies that fall into this category have at least two layers of documentation: Developer Docs and API Reference. Companies with both docs and API reference split doc visitors into two cohorts:

• Developers who are interested in higher level integrations or SDKs
• Developers who are interested in the raw REST API or API wrapper libraries

The main developer center or documentation hub doesn’t discuss the REST API at all, nor does it discuss API wrapper libraries. Instead, there are navigational links from the docs to a separate and independent API reference website. Many times, the API reference uses a different design or layout compared to the rest of the documentation such as a 3-column or 2-column layout. With this approach, the documentation home provides getting started guides and information on how to use or integrate each product feature.

Companies that follow this approach may be very API-focused or developer focused, yet already have higher level integrations so that working with the API directly is not required by all visitors. Such companies include Stripe and Moesif. Stripe, for example, showcases their Stripe.js and Android / iOS SDKs front and center compared to their REST API placement.

Moesif developer hub provides navigational links and separate API reference

Many developers will not need to work with their REST API directly as there are higher level integrations to get started with. Thus, a NodeJS developer visiting the developer docs for the first time will probably be more interested in a higher level SDK rather than reading about the raw NodeJS API wrapper lib. Remember, while you are probably very intimate with your own API and its SDKs, a newcomer developer may not be.

Benefits

• Can drive new people to the appropriate getting started guide and avoid confusion around too many integrations.
• Navigational layout can be designed specifically for documentation type. For example, the API reference can be a single long page, whereas general docs are split across many smaller webpages.
• Separate API reference is useful to document REST APIs that are very CRUD like.
• Gives power users an excellent bookmark-able and SEO-optimized API reference URL for things like entity schemas without digging through verbose getting started guides.
• API reference site can use a separate tool chain and leverage third party doc generation solutions like SwaggerHub.
• Can be ideal for companies that have a clear division of responsibility between who owns the API reference vs developer docs & guides.

Downsides

• Not ideal for companies having a single tier of integrations.
• Can artificially force the API reference to take the backstage which may not be your business requirement.
• Centralized navigation may not scale well for companies with many distinct product lines.
• Terse API documentation may scare non-developers away.
• Can decentralize critical navigational elements like search.

2. Centralized docs combined with API reference

Companies that fall into this category combine their HTTP API reference with the rest of their developer docs and have no separate API reference website. In this situation, while the API reference is combined with rest of developer docs, there is often a separate non-developer help area. Companies with combined developer docs tend to split visitors into one of the following cohorts:

• Developers who may use an SDK, integration, or possibly the raw REST API.
• Optionally non-developers who just need to understand how to use the dashboard or product.

Mixpanel and Amplitude both follow this approach pretty closely. Square also follows this with the Square Docs.

Mixpanel documents their HTTP API reference alongside language specific libraries and SDKs

These companies market to both developers and non-developers. For Mixpanel and Amplitude, the primary user is not necessarily the developer who integrated the product. Rather, Mixpanel and Amplitude are marketing their product to data-curious marketers and product managers. Square is marketing their product to merchants and retailers. These companies are often marketing the flexibility of the product rather than the flexibility of the API.

These types of companies may require documentation for both developers and for non-developers. A Separate API reference would create three levels of documentation: non-developer help, developer docs, and API reference. Adding a third level for API reference can cause confusing navigation or scare the primary user away.

Combined docs can also be used when there isn’t a clear distinction between integration SDKs vs REST API and API wrappers. If all your integrations are API-centric and you can’t cleanly bucket your integrations into API centric and non-API centric categories, then you can possibly create a navigational nightmare where it’s hard to view and search all integrations in one place if you used separate API documentation. Combining HTTP API reference with other guides enables you to easily have how-to guides all centralized and searchable in one site.

If you look at Algolia’s docs, while they do somewhat separate their raw REST API, all other integrations are at the same level. For the most part, Algolia is a blend between the first approach and this one.

Benefits

• Avoids having too many doc sites such as non-developer help, developer docs, API reference, etc.
• Ensures the HTTP API is at the same level as other integrations and not backstage.
• Easiest layout when writing new docs for a new product with minimal content.
• Documentation search can be centralized, useful if some features require your API while others require an SDK.
• Avoids scaring non-developers away by having docs that are terse and too “Developer or API centric.”

Downsides

• Can cause confusion by integration overload if you have both lower level and higher level integrations.
• Hard to scale internal teams especially if the API maintainer is different than general developer docs.
• Have to compromise on navigation design as certain elements may be better suited for navigating API reference vs. navigating general docs.

3. Decentralized docs

Decentralized documentation is quite different from the other two categories. Rather than centralize types of documentation in the same site, they choose other pillars to organize their documentation around, such as product lines. These companies split doc visitors into specific cohorts based on the product or service that the visitor is interested in.

As an example, Twilio’s products include not only SMS messaging, but also authentication and video, thus they silo Twilio’s docs along product lines rather than docs vs API reference. Many of Twilio’s users who want to integrate Twilio’s SMS product may not care about their authentication product Authy.

Rather than cluttering a centralized doc site, these companies decentralize such that when viewing Twilio’s API reference, you’re only viewing the documentation related to you. If interested in Authy, then you only browse Authy’s documentation. Decentralized docs can help large companies who don’t have centralized documentation teams, where each product owns its respective documentation.

With a decentralized approach, documentation is catered to products and specific visitor cohorts

Benefits

• Declutters complex product lines, can be useful for large enterprise products.
• Enables the company to scale documentation by product teams. Just need a small central team to maintain cross-cutting design and infrastructure.

Downsides

• Can artificially silo products that are meant to be interconnected. For Twilio, SMS and Authy are truly unrelated products. However, you wouldn’t want to silo separate, yet related features within the same product.
• Hard to organize getting started guides if same library or integration is used across product lines.

5 Specific Features to Boost Site Architecture

Each company and its documentation needs are unique. There are a few trends around specific documentation features discussed below that are used among popular companies like Stripe and Auth0. You can use these as inspiration for crafting your own API documentation sites:

• Sticky Navigation: Sticky navigation is a must have for anyone creating long documents as it keeps the navigation sidebar always in view. Examples of sticky navigation can be found in Stripe’s, Auth0’s, and Algolia’s docs.
• Saved scroll state: Saving scroll state can be useful if the user refreshes the page. You can even add the nearest header link into the URL as a hash link in case a visitor copy/pastes the URL from the browser.
• Sidebar navigation styles: Accordion and non-accordion left sidebar navigation are both heavily used for documentation and depends on factors such as number of navigational links. You can leverage open source projects such as Navgoco to create awesome accordion style navigation.
• Three-column documentation: Consider a 3-column API reference using Slate as a boilerplate. 3-column docs can be useful for CRUD style API reference where the core API reference is the same regardless of language, but a visitor can quickly see the specific implementation in his/her primary language as well.
• Edit on Github button: Storing your documentation on GitHub or similar makes it easy for developers to contribute to your docs. An Edit Me button which points to the source repository can encourage community engagement and ensure your documentation is corrected for mistakes. Larger organizations like Microsoft Azure have a Github button in their published docs which points to azure-docs on Github.

The Right Doc Setup for Your Environment

There are many ways to design and organize developer documentation, and each company will have specific requirements around their documentation. Yet by researching common design patterns in modern developer documentation, you can ensure your developers will find the help they need. Your documentation can also be a powerful marketing tool, which means you must treat it like a sellable product. Do A/B testing and constantly ask others for feedback. After all, it’s a living document.