Five ways to improve SEO of your technical documentation and OpenAPI references

Do you know how your readers reach your documentation site? Some of them may have bookmarked it, others may have clicked on a link from your website. But many of them will have found it through a search engine.

Unofficial studies show that the majority of website traffic comes from search engines. This is why it is important to make sure that your documentation is optimized for search engines.

In this article, we will look at five ways to improve the search engine rankings of your docs and OpenAPI specification.

Dogfood! Use your own documentation

The best way to get a feel for how your readers use your documentation is to use it yourself. This will help you identify areas that need improvement. It will also help you understand how your readers use your documentation.

Consider doing the following:

• Regularly try to search for a topic in your docs, and see if you can find it
• Gather feedback from power users. It may be your customers or your support team
• Periodically search for phrases on Google and see if your documentation appears in the search results
• Consult a keyword planner or SEO tool to see what people are searching for

Make sure your content is indexed

To have your content indexed by search engines, you need to make sure that it is accessible to search engine crawlers.

Metadata helps bridge the gap between your content and search engines. It’s a good idea to consider your documentation page’s title from the perspective of someone entering your site from a search engine. The title should be descriptive and contain keywords that are relevant to your content.

For example, consider writing “How to get started with the Doctave API” instead of “Quick Start” as the page title. The former is more descriptive and will help search engine users understand what your content is about. The latter is what you would use as the h1 element on the page.

Make sure that:

• You don’t block crawlers in your robots.txt file
• You have submitted your sitemap to Google Search Console
• Pages have a <title> tag and a <meta name="description"> tag
• You use keywords in your image alt tags

Use keywords in your content

Search engines use keywords to determine the relevance of a page for a given search query. Make sure to express yourself in the language of your readers. If you are writing for developers, use the same terminology they use.

Consider what your readers are searching for. Bear in mind that people may search for something with wildly differing queries. A search for “api documentation tool” may be equivalent to “api static site generator” or even “technical documentation wiki platform”. If you have access to a search engine’s keyword planner, you can use it to find out what people are searching for.

Note that keyword stuffing is not a good idea. Search engines are smart enough to detect this and will penalize you for it. Instead, you should use keywords naturally.

Make sure that:

• You use a varying set of keywords to describe your content
• You use natural keywords in your page titles and headings
• You monitor popular search queries and update your content metadata to improve discoverability

Ensure your content is linked

Search engines use links to discover new content. Make sure that your content is linked from other pages on your site. This will help search engines discover your content and will also help your readers navigate your site.

When linking, be helpful. When you’re writing about a feature on your blog, link to the documentation for that specific feature, instead of the documentation root page. Save the reader a few clicks.

Make sure that:

• You link to your documentation from your marketing site
• You link to your documentation from your blog

Update your content regularly

Readers and search engines alike prefer content that is up-to-date. Make sure that you update your content regularly.

Your sitemap.xml should be updated automatically when you publish new content. It contains a list of all the pages on your site, as well as the date when they were last updated.

Make sure that:

• You periodically review and revise most popular content
• You update your sitemap.xml when you update or publish new content

Enrich your OpenAPI specification

If you are using OpenAPI to describe your API, you can use the tags field to add keywords to your specification. This will help search engines understand what your API is about.

Include a description of your API in the description field. This will help search engines surface pages for your API’s operations.

1
2
3
4
5
6
7
8
9
10
11
12
13

openapi: 3.0.3
info:
  title: Example API
  version: 1.2.3
tags:
  - name: Accounts
    description: |
      Operations related to user accounts.
      Use this endpoint to create a new user.
  - name: Billing
    description: |
      Operations related to billing.
      Use this endpoint to get the current balance.

Additionally, the externalDocs field can be used to link to your documentation. The field can be added both to the root of the specification, tags and to individual operations.

1
2
3
4
5

tags:
  - name: Accounts
    description: ...
    externalDocs:
      url: https://docs.example.com/api/accounts

Summary

In this article, we looked at five ways to improve the search engine rankings of your technical docs and OpenAPI specification.