Optimizing documentation for search

Here’s an obvious statement. Well-optimized documentation for search is important. And, I’ll try to cover everything I think will make your documentation rank better and be helpful to developers right where they search for the answers.

Subdomain vs. subfolder

I’ll always prefer a subfolder (/docs) over a subdomain (docs.) approach, mainly because in practice I’ve seen quite a few examples where traffic went up for both main domain and subdomain pages after the merge. On top of that, it’s a live and forever debate in the SEO community which revolves around “it doesn’t matter” or “subdomain is worse”. Given that keeping everything in the subfolder doesn’t hurt in any case, it’s just a “better safe than sorry” type of situation. So, where technical means allow it, subfolder is the way to go. Here are the ways to achieve it:

• Either you have the same frontend tech-stack for everything, or
• You can set up a reverse proxy to serve docs content from another (sub)domain on /docs, but bear in mind that this will introduce some additional latency.

Docs versioning

Here’s another obvious statement. Docs are a living thing. Given the fact that they follow product development, things can change frequently, items deleted, merged into another topic, separated into its own topic and more. And, more often than not, bigger changes will prompt the company to create another version of the docs and SEO-wise, this can cause a lot of breaking changes.

URL structure

It matters a lot more than we’d like it to be. One decision you’ll have to make is whether to keep things in a separate folder such as /docs/v2/ or use the parameters such as /docs?version=2. Whenever faced with this choice, always go with the former. The way query params are treated leaves things to interpretation and it might cause search engines to completely ignore them, especially if the content overlaps to a large extent. Paths are considered distinct URLs by default while that is not the case for query params.

Another thing that might come up is “why would we struggle with creating new pages in the existing project when we can just copy it and spin up another instance on v2.docs.example.com?”. It is similar to what I wrote about the subdomain vs subfolder. Subdomains are often treated as their own entities and, if separated, they need to build their own authority from scratch.

Now, once you've decided on paths, you still have a choice to make. Do you put the latest version at /docs/feature and versioned ones at /docs/v2/feature? Or do you version everything explicitly? One way to go is keeping your strongest URLs clean and short, which is better for link building and sharing. Old versions live under their version prefix, and if at some point you decide to completely deprecate the old version, you have a few options:

• A permanent (301 or 308) redirect to the latest version.
• Return 410 for a page that's genuinely removed and won't come back. Make sure you don’t have any external links (through Ahrefs or a similar tool) before that. If you do, just redirect it to something relevant.
• If you want to keep it for the users but not have it indexed by search engines, either add Noindex in meta robots or a canonical tag to the newest version in order to not compete with your current docs.

You can find a guide on meta robots here.

One thing to consider is, if you decide to keep one master URL which always keeps the latest version of the docs, you would want to make it clear on the page itself as otherwise it wouldn’t be clear from the URL itself.

Canonical tags can be super helpful if a lot of the content overlaps. For example, you might have an authentication guide where things changed just slightly, but you still have to maintain two versions to keep the new docs coherent.

You can find a guide on canonical tags here.

Structured data

By structured data I mean schema.org and other HTML-related structured data you can provide to the search engines so they can understand your content better.

HTML structured data

Make sure your images have alt text and try to be specific. On one hand you are improving the accessibility of your docs, on the other you are giving search engines a little bit more context to work with. Ideally your filenames would also provide some more context. Here’s a guide on how to write descriptive alt text and more.

While not a ranking signal, it would be great to also add OpenGraph. Developers will share links on Slack or a social media platform and you want to provide them with the best experience.

Schema.org

I think the simplest way to implement schema is to use JSON-LD as other ways make things a tad too complicated by having to exist within HTML. Start with BreadcrumbList. It's usually the lowest hanging fruit. Your docs already have a hierarchy, breadcrumbs make that hierarchy visible in the SERP, and they're crawlable navigation on top of that (more on that in internal linking part).

For tutorial-style pages, HowTo schema works well. When your docs walk someone through a process step by step. It's not going to work for reference docs, but for guides it fits naturally. SoftwareSourceCode schema type can help Google understand what language you're writing in and what the code is actually doing. Not every search engine uses this yet, but it's a signal that costs us (almost) nothing to add.

If you have video tutorials embedded in your docs, VideoObject schema makes them discoverable outside of your website. Same idea with FAQ schema for pages that have a questions-and-answers section. Google will sometimes surface these as rich results, and even when it doesn't, you're giving the engine more context about your content.

Internal linking

The rules here are super simple, you want to link internally as much as possible. I’d argue it’s the most overlooked thing in SEO and, with a little work, the outcomes can be great.

One rule of thumb though on the development side is you want to use/render <a> tags for all your links. Anything else, such as <button>, JavaScript interactions and similar are making it super hard for search engines to discover the URLs.

And actually, I’ve got one more. Keep anchor text contextual as well. Instead of “here” and “learn more”, always try to link the part of the text that describes what’s on the URL you’re linking to.

The first thing to look at is your side navigation. The structure of your nav directly impacts how internal URLs are discovered and how page authority flows through your docs. If your navigation is too deep or too fragmented, pages buried three or four levels down are going to get crawled less frequently and accumulate less authority. Try to keep things as flat as you can without making the nav unusable.

Next and previous links in doc sequences are another easy win that most sites skip. If you have a multi-page guide, linking each page to the next and previous one creates a crawl path that lets search engines discover everything in order. Google itself no longer uses it, but Bing does and it’s still a general good practice. It also helps the reader move through the content without going back to the nav every time.

One other simple way to add a bunch of pages to the docs is to use your changelog page to link to any docs page that is related to the release. Also helps the user get a more detailed understanding of the changes.

Cross-linking between your blog and your docs is one of the most underused channels. And, it’s mostly a coordination problem when the person writing a blog perhaps isn’t fully familiar with the docs. However, it’s a natural flow, guiding the user from a more general guide more towards product content.

The oldest trick in the internal linking book is adding some related items somewhere on the page. Most blogs do this, I also do it on devtooljobs.com and it really helps the discoverability of new URLs and helps keep things well connected.

Stripe docs are often cited as a great example from multiple standpoints and for a good reason. Each guide is so well explained, connected and linked out and everyone should take an inspiration.

Content / UX

Should the search functionality within your docs help with SEO or is it purely a client-side thing? The short answer is it should be client-side only. A search results page within your docs is almost never something you want indexed. It's thin content, it's dynamic, and it competes with your actual doc pages. Let your internal search do its job for users, but keep it out of Google's way. If you use query params for search, the way to achieve this is by adding a canonical url from the search results page to the home page or /search if you have something like that.

Put some effort into writing the meta description for a page. While not a ranking signal it helps improve the click-through rate (at least for the times when search engines don’t just pick up something from the text).

When it comes to code snippets, I’ve got three things to say. One, if you are using a syntax highlighting library, they can cause the page to load a bit slower so always load syntax highlighting only for the languages that you use instead of everything the library provides. Two, try to provide try to always add some more context around a code block such as titles or captions. And finally, click-to-copy has become a standard nowadays with code snippets. Users expect it in most cases so adding this option affects user signals (it’s also just normal).

Another relatively established good practice is to add a table of contents on longer pages. Helps the user navigate and helps create site links in SERPs. In addition, you want links to subsections to be descriptive so pretty much slugified subheading and not some ID or something like that.

If you're embedding something like CodeSandbox, the content inside that embed is not crawlable. Search engines can't see it. So if your interactive example is the main way someone is supposed to understand what's happening, you need the explanation to exist in crawlable text too. Treat it as something that helps enrich your page and not as a substitute.

Troubleshooting section or error message documentation is a great way to rank for more long-tail keywords and also attract backlinks from other websites writing the guides (and this works well for LLMs, too). Essentially try to pick up what errors and similar developers might be searching related to your product and build out pages that answer their queries. Vercel does this very well with their errors section. Each error is a different page that helps the user understand where the problem is.

In Google Search Console, you can get plenty of ideas on what may be missing from your docs. This deserves a separate guide, but in principle, you just need to check the queries a page ranks for and there might be some long-tail stuff that your docs don’t address yet.

And finally, docs tend to contain architecture diagrams, screenshots and similar. Make sure these images are optimized so that they don’t affect the page load time.

Treat this guide as “this is something we strive for”, but never go SEO-first. Almost none of these should ever go over what’s best for the user in your situation. And, situations can vary.