Select Page

DEVREL SEO for API and SDK Technical Documentation

by | Jun 24, 2021 | Articles, Developer Marketing Articles, SEO Articles


Optimizing technical content for SEO is similar to optimizing content aimed at consumers for SEO. The whole goal is to get people to get benefits out of your content. If you do that, then Google will reward your documentation with higher search results and intern a higher portion of the traffic that you can convert into paying clients.

Killing 2 Birds with 1 Stone

Getting traffic to your website for your API or SDK or even SaaS is hard enough.  One of the best ways to rank for keywords is actually by taking advantage of the content that you are already creating. This is usually in the form of documentation.

In this article, I will walk you through the typical “big-win” fundamentals of doing SEO for technical documentation, but please understand this is only the tip of the iceberg when it comes to SEO.

Whose Responsibility is it Anyway (Marketing or Engineering)?

The problem with documentation is that it usually lives within the responsibility of the engineering team to both produce and publish. Sometimes the engineering team will employ a technical writer to help them fill in the gaps, clean up the grammar and make it easier for an outsider to read.

The problem with this setup is that the engineering team is not focused on user acquisition.  User acquisition falls to the marketing team. If you are reading this you are likely either a very savvy marketer (who is seeing conversions from the technical documentation) or a very savvy engineer (that realizes documentation shows up in Google Search Results) and have realized that some new clients of your company are coming from your documentation.

If you already have a firm grasp on all this check out my article on my take about “How to Market to Developers” (the next phase of this process). This article focuses on the table-stakes to get real traffic from Google Searches.

Benefits of SEO Optimization for Technical Documentation

People visiting your documentation website from Google is a free source of potential new users. Much of the traffic will be existing users looking to answer questions, but a subset of them will be new users that have never heard of your product or service.

Your technical documentation is actually driving the “Discovery” of your brand and further building awareness of your product just by being as authentic as it can. It is just documentation, but it is answering questions that people have and that in and of itself is the intent of Google.  A match made in heaven right?  Well, sadly the search volumes are very small.  Some of the most valuable keywords may only get 10-15 searches per month, but those searches can quickly turn into really big revenues. Imagine if NASA was looking for a very niche product for a 15-year $150MM contract that only your company had the only available offering and they Googled for it and found your company’s documentation and found that your product did exactly what they were looking for and reached out.  That’s the power of documentation and making sure that it shows up in the right spot where your potential clients are searching for answers.

Optimized technical documentation brings a high level of 

  • Awareness of the product within the right communities
  • Targeted readers (because frankly, you don’t want consumers wasting your time right?)
  • Efficient content production – build this into your documentation generation steps and forget about it!

The Downside of SEO Optimization for Technical Documentation

Sounds like the perfect solution for marketing right? Fire the marketing team???  Hold your horses, marketing still has its role as does engineering. There are some downsides that really do need a good marketer’s help.

  • You still need marketers to enforce brand concepts like tone, vision and consistent messaging
  • They will also focus on topics like branding, go to market and Off-Page SEO to further get the word out. Marketing is a complementary force in the world of getting content in front of the right developers. Keep the team!
  • Marketing will also monitor the progress of this work and offer tips and tricks over time to produce better CTA’s (Calls to Actions) that work and potentially represent the customer in the process.

Low Search Volumes, but High Rewards

Let’s take a step back for a moment. Even the most popular frameworks, languages, operating systems and API’s all started small and had zero “branded” search volume, so what did they do? They slowly but surely built a suite of documentation that was helpful and answered questions, they built a community of enthusiastic friends and built a brand.

All of this takes time and so does SEO work.  Most of the sites I work with don’t rank (show up in the top 10) for their target keywords for 6+ months! The best thing to do is get your site functioning properly so that Google can index the pages, make sure it solves the end user’s problems and then start tweaking.

I have listed out a rough plan of attack, but for each SDK or API it may be different, this is why you reach out to a consultant who can run a review of your site and then tweak the below list and plan of attack depending on your goals, current setup and available resources.  I know of a good one here (

Plan of Attack

So where do you start? Below is a list of potential things you could be doing, but they are not prioritized for your situation nor are they the only things that can be done, but it is a good reference.

Step 1:: Get the Site Functioning Correctly

Domain vs. Sub-domain

  • If you choose to host your technical documentation in a sub-domain, just realize that Google treats that sub-domain as a new website. It will NOT help the SEO of your main website. You will likely end up with more traffic to your documentation than your marketing site. The best thing to do is host the technical documentation on your marketing website’s domain.


  • Recently Google started emphasizing that page speed will soon be part of its ranking algorithm, so make sure that it is responsive and quick to your target demographic of potential clients.


  • This may sound silly, but you want to only load the images found in your documentation when the graphic is shown.  This is called Lazy-loading and there are many plugins and most CMS systems already support it. Do it, it will save you money and people’s time.
  • Also correctly adjust your imagery for the viewport.  If your documentation is only 800px wide, you only need an 800px wide image within that documentation, not 3200px wide.

Step 2: Let Google know Your Site Exists


  • If your side does not have a sitemap, get one created and make sure that it is properly formatted.


  • Make sure that your documentation has a Robots.txt file and is allowing search engines to index your site. Don’t forget there are other search engines out there like Bing and DuckDuckGo.

Submit Sitemap

  • Once you have a Sitemap, make sure to submit it to the search engines.  It doesn’t take but a few moments to do so, but once you have then the search engines will use this as a reference when they do their crawling.

Step 3: Setup a Reporting Cadence for Your Site

Automate Reporting Tools

  • Some teams have resources to do this themselves, but I recommend using the available tools from Google to monitor your technical documentation at the start and then work to figure out which metrics you actually need. Once that happens, Google has API’s where you can pull out the metrics yourself and build something like a Grafana dashboard to monitor your site performance.

Step 4: Format Your Site’s Content Correctly


  • One of the best ways to help search engines to process your technical documentation is to structure it simply, plainly and not too deep. Use headers in your documentation to help the reader easily process your content and skip around as needed.
  • H1 – Use only 1x H1 for each page. It should be both the largest piece of text on the page and the Title of your page. Try to formulate it so that it exactly describes the intent of the page.
  • H2 – Use these for a section of your page. Use them at will
  • H3 – If you have sub-bullets or sub-sections within a section, use these but rarely. If you feel that you need to use H4, consider rearchitecting the content so that you do not need to do this.

TOC if long

  • If a specific page has more than 4 sections, build a table of contents at the top of the page that links into the rest of the page. Nobody wants to scroll through a mountain of text.


  • Make sure that you have a meta description about the page on the page. This will help control what Google shows to end-users. If you do not have a meta-description, Google will generate one for you and that may not be what you want in the long run. I have found that using the introductory text of a page works well for technical documentation. It gives a nice preview.

Inter-linking of relevant topics

  • If you have relevant other topics in your technical documentation, be sure to link it from your content. This will help engagement on the site and keep people on your domain longer.

Call to Action (CTA)

  • In your technical documentation be sure to craft a reusable Call to Action (CTA) that your potential client knows exactly what to do to sign up for your product or service. Sometimes when you are below the fold, people do not know what to do next. You want them to sign up!

Ok with all that out of the way you may be thinking to yourself that this is a huge amount of effort. That is where you are right, but it is only a fraction of the effort it took to build your product and the technical documentation that went along with it. Also, it may turn out that this is your biggest asset when it comes to building your own developer clientele. 

Just as I have tried to teach you above, my CTA to you is to get in contact with me for an initial review of your technical documentation, marketing page or other websites and I’d be happy to help you through the process of going from the 15th page of Google to the first!

Phil Johnston

Phil Johnston

Owner, Hakungala

Phil has been building, growing, and marketing developer products for the past 13 years. Starting in 2008 with his company ORCA Digital Services, followed by BMW Apps, GoPro and HERE Technologies he gained his experience in selling APIs to developers of all walks.

Most recently, Phil has been helping companies on both tactical and strategic projects.

Feel free to reach out to chat with Phil.