How to Optimize Technical Documentation for Search

Forgetting to optimize technical documentation for search, otherwise known as SEO (search engine optimization), is a missed opportunity. For starters, you already have the upper hand: Assuming that you know how to create good technical documentation, you have informative, actionable, and pre-written content ripe for crawlers and users alike.

Having written technical documentation in the first place, you’re already following the first, but often-forgotten principle of great SEO: Ranking well and consistently requires informative content, rather than marketing drivel.

With that in mind, here is how to SEO your technical documentation.

Choosing the Right Platform | Indexing Your Documentation | How to Structure Content | Common Content Mistakes | Keyword Research | SEO & Quality | Titles & Metas | URL Optimization | Types of Links

Getting Started

Use an Established Platforms To Boost Technical Documentation SEO

Don’t have a website yet? Go with a household name like WordPress, Drupal, or Mediawiki.

Platforms like WordPress have automated much of the technical SEO you’ll want for your documentation — and any other keyword-oriented content you publish on your website later. WordPress specifically is great with:

  1. Canonical links
  2. Sitemaps
  3. Site structure
  4. Redirects
  5. Robots.txt files
  6. Meta descriptions
  7. Schema markup
  8. 3rd party SEO plugins, such as Yoast

WordPress is janky, but having your website do all the above without you thinking too much about it is critical for technical documentation SEO.

Alternatively, you can build a static website, but implementing the above will take significant time and effort.

Have You Already Published Your Technical Documentation?

Great. To check how “good” your website is in terms of SEO, check for alerts in your Google Search Console (see next section) and Google PageSpeed Insights.

If you’ve already published your technical documentation, make sure that it isn’t using iframes.

No matter how good of a user experience you think this provides, do not use iframes for this reason. No exceptions.

Should I Migrate My Website to a More SEO-Friendly Platform?

Generally, no, as migrations are a hassle and you should probably hire someone for it. However, if your platform makes canonical links, redirects, schema markup, sitemaps, and robots.txt files prohibitively complex for you, AND your website is small, you may consider it.

2. Have Search Engines Index Your Documentation

The first step of good SEO for your technical documentation is making sure users and crawlers can find it. If people don’t know that your product or code exists, don’t know why they should use it, and don’t have support figuring out how to use it, they won’t.

If your documentation isn’t already published, do that now. As long as what you have is to your liking, don’t worry about having it perfect SEO at the moment of publishing.

How to Index Technical Documentation

Once you’ve published your documentation, let search engines know it’s out there. Do this by heading to Google Search Console and indexing your website.

This is easy: First, verify your DNS then submit a sitemap.

A sitemap is a list of all of the web pages within your website. The point of a sitemap is to help search engines discover all of your website’s content and understand how pages relate to one another.

Once you have Google Search Console set up and have your documentation on one URL (more on this later), submit the URL for indexing.

Won’t Search Engines Find My Documentation Anyway?

Yes, but it may take weeks or months for crawlers to discover a webpage. Whenever you change a webpage, you should resubmit it to Google Search Console.

Unless you frequently update your website, it is unlikely that crawlers will discover new pages or that Google SERPs will reflect content changes.

Content Marketing

Though a spammy term in some technical circles, content marketing is essential for having great technical documentation SEO.

How to Structure Your Content

The following are the rules that I follow   no matter what I am writing. I have had tremendous success with them and suggest you follow them, too.

  1. Only use one H1.
  2. Use other headings in descending order (ex: do not use an H1, followed by an H4).
  3. Use your keyword (perhaps a product name) in your headings, rather than just writing “Conclusion.”
  4. Replicate the structure of articles that you enjoy reading on your phone.
  5. Use bullet points and numbered lists.
  6. Write a meta description between 120–150 characters for every page.
  7. Use at least one image per URL.
  8. Add alt text with your keyword(s) to every image.
  9. Use your keyword(s) naturally throughout your content. You want them to be there, but not in a spammy way.

The Worst SEO Content Mistakes that Documentation Writers Make

You want to have one page be the authority on any given topic. If your website starts ranking well for a specific keyword, do not go off and create more pages targeting that keyword.

If your website is dedicated to one product and your product name is your keyword — rather than its functionality, for instance — you will have to be clear on what is the authoritative page for that product.

For example, though this website sells scuba diving equipment, its collections page is the authority on the keyword “scuba gear” rather than the homepage or a product page. You will have to be similarly crafty with your site structure.

I cannot stress enough that you do not want to divide content between multiple URLs. Backlinks remain a large part of Google’s ranking factors.

When you change your URLs, you diminish your backlink strength.

When you divide content onto multiple URLs, Google does not know which to rank so it won’t rank any of them well.

Choose Your Keywords for Technical SEO Search Engine Optimization

Though an overused buzzword, keywords remain a critical part of content marketing. Why? Google Search can only display content based on the words that a potential website visitor searches.

A keyword could be your product name or its functionality, generally depending on your marketing strategy and brand recognition. Ideally, though, you want to target both through two landing pages.

Make sure that your keyword appears throughout your content but don’t keyword stuff. Use it in ~75% of your headings, too.

A Framework for Quality Content

The best way to have your content rank better is to make it compelling.

The Best Technical Documentation Is Accessible

Have someone who is smart but less familiar with your product read your content. Does it answer all of their questions? Is it easy to navigate? Is the prose succinct and easy to understand?

Complexity in writing is almost always unnecessary.

Content Isn’t Just Written

Not only do humans love visual content, but crawlers do too. I have seen infographics have a great effect on SERPs rankings and drive significant traffic from Google images.

At the very least, have a hero image for your technical documentation. It doesn’t need to appear on the page, either.

Start Search Engine Optimizating Your Documentation with Metas and Titles

So, you have to restructure a massive piece of content and aren’t sure where to start, short of emailing me for help, start with titles and meta descriptions.

Not sure what these should look or sound like? Google your keyword and see which results come up first. Then write metas and titles of similar lengths that are better.

Technical SEO

Put All Technical Documentation for One Product on One URL

If crawlers are confused about which page is the authority on a certain topic, they will rank you poorly. Having a stable, authoritative page is critical for technical documentation SEO.

Do not change your URLs ever unless you meet one of the following criteria.

  1. Your existing URL is challenging for humans to read, e.g. includes a random string of numbers or text.
  2. Your URL is unnecessarily long. It should include only relevant terms, no dates, prepositions, or unnecessary folder names.
  3. Your URL does not include a main keyword — search term that a potential user types into Google to reach your product — or the name of your product.

If you do meet the above criteria, you may change your URL once. Make sure that you redirect your original URL to the new one.

Don’t Prioritize UX at the Expense of Your Documentation’s SEO

Do not use iframes. These divide your content onto different URLs.

But they make for a better user experience.

It doesn’t matter how good your user experience is if no one can find your website in the first place.

I know software people love a table of contents, but please don’t use iframes to hide searchable information. I am all for a table of contents as long as all the relevant content for your specific keyword is fully visible on one, static URL. This is easy to do.

3 Types of Links That Matter for Your SEO

  1. Canonical Links: These tell Google which URL is “canon,” meaning the authority on a certain topic. Without canonical links, you will get a demerit and your rankings will suffer.
  2. Redirects: 404s are black holes for your website. Use a free 404 checker and find all broken links. Redirect them to the most relevant pages.
  3. Internal Links: Without internal links, your web pages become orphan pages, meaning that they’re a dead end (bad) for crawlers. Interlink all of your content in a sensical fashion and use links to point to the authoritative pages on specific subjects.

Yes, You Can SEO Technical Documentation Without Diminishing Quality

I often hear concerns that including keywords in your content will reduce its quality. This happens all the time, but it doesn’t need to.

Think about it this way: Science fiction is a more effective way for authors to critique our society and actually get the message across. SEOing your technical documentation is no different: If you want people to use your products, you need to make your content accessible. There is an art to doing this without losing value, but creativity thrives within parameters.

If you’re able to optimize your technical documentation for search engines without diminishing its quality, you’ll be head and shoulders above the competition. If it were easy, everyone would do it.