SEO for technical documentation is stuck in a kind of parallax place. It’s such an obvious need, and servicing a customer base which is so often taken for granted in design (“they’re used to messy navigation”; “they’ll find it, right?”; “they can always send us an email”), that it is almost never undertaken. But there are steps you can take to make sure that your documentation properties are properly serving your customer base.
The basic steps for docs
First, the obvious. You should be observing a number of standard publishing governance standards and best practices for your sites, to include at least the following key steps:
- Distinct title tags which accurately describe the contents of your page.
- Distinct headings across your pages which also accurately describe the contents of your page.
- Important page contents are available to search engines in the raw HTML, or are delivered in JavaScript which you have validated to be search-engine renderable, and proven not to give way to indexation issues.
- Text, written in complete sentences, describing actions to take, describing cases in which specific actions should be taken, and describing (in captions) the screenshots included on your pages.
- Alt texts for images, including screenshots.
You can access a great list of basic governance features through Gitlab’s SEO wiki.
SEO steps specific to docs
For docs properties in particular, you may face sets of issues that colleagues working on more conventional instances never faced or have long since resolved. To a large extent, these are a product of how docs properties are built and who uses them. In many cases, SEO-related difficulties in design, navigation, or linking practices can also be attributed to the fact that ownership over docs is usually far and away from marketing or growth functions. For that reason, control over some of the basic web standards which comprise SEO “levers” are simply not built into documentation management practices.
Here are some of the steps you can take to ensure your docs are well-optimized for organic search:
- Elaborate an intuitive linking structure. Fortunately, nesting according to topic is quite achievable out of the box with major documentation platforms, but that can become overwhelming as pages scale.
- Pursue some level of control over crawling and indexability on your documentation properties. While indexability of pages will most likely not be an issue according to default settings, control over crawling and indexing directives may be. If you purchase an out of the box publishing platform solution, it is very possible that they may control your robots.txt file, and that no control over your <meta> directives is available through their publishing interface. If that is the case, you should work with your developers to introduce custom solutions where necessary to gain a strong handle on these. As docs managers well understand, pages may simply get unlinked, buried, become redundant, or need to be temporarily hidden while clarity is sought.
- For the same reason, having control over your hosting interface can be make-or-break in terms of your ability to set redirects. This is critical to make accommodations for adjustments to your property (for example, deleting pages or folder structured), and avoid messy status errors that lead to Google thinking hidden or unpublished pages are still available. Since there is no guarantee that you will be able to control your redirects file from within a docs CMS, you may need to handle them from within the hosting provider’s provided redirects panel, for example a cPanel with control over URL forwarding. In many cases, you will have to figure this out on your own, as documentation publishing platforms – similar to platforms for publishing other specialized content – generally have reduced awareness of SEO best practices, despite appearances. Here’s a very representative SEO horror story, involving a migration for zendesk to intercom.
- To make sure that you “own” the domain from a search-engine point of view, a custom domain is important. Consider some of the highest traffic zendesk properties (which are technically “Zendesk’s” properties):
Providers like Zendesk or GitBook offer custom domains during setup or host mapping to bring custom domains online. These solutions are important if you want to be able to control, measure, and leverage your docs on organic search.
- A last argument in favor of hosting. If you have a lot of pdfs in your documentation properties (as for example AWS does), control of hosting will likely also amount to control over indexation of pdfs. For these pages you need to embed your indexation directive in an HTTP response header, rather than in the html body. That functionality will most likely not be available in a CMS interface.
Why bother with SEO for docs?
I will write a separate post about SEO strategies for documentation properties, extending each point below and adding others. Here I will provide a few first on how to think about SEO for docs, and why you should care.
Documentation is for sales and retention (not information-idling)
If you have documentation, chances are that your end-user is already a developer. For evaluating product capabilities and how it fits into their stack, they are probably considering your documentation pages more than your marketing content.
In terms of how you think about your documentation properties from an SEO perspective, I think that treating them as passively informational is the wrong way to go. Similar to a product page, your docs pages provide critical details for consideration – it’s just that in this case, what is under consideration isn’t necessarily the look, feel, or price of a product, but some of the fundamental details which are more relevant for this specific type of end-user in the purchasing funnel. In a way, these are not just product manuals but also product pages.
The same logic applies with respect to business goals like retaining and upselling customers. Customers will be regularly seeking out and accessing information on your docs. If they are unable to find information they need, that presents a usability issue. This may put unnecessary pressure on post-sales teams to answer questions which customers may prefer to have answered on their own time and with all needed information available for their consideration.
Search is how people access documentation (when you’re not emailing them links)
Google’s original PageRank was built as an algorithm for link-scoring. In this model, a page’s value is determined by the value and quantity of pages which link to them, divided by the quantity of links outbounding from those pages, and with some dampening of the score of the outbounding page. The value of all other pages is in turn determined by the same basic factors.
The logic behind this model assumed that number and “score” of inbounding links could be used as a heuristic for the likelihood that someone surfing the internet as a Platonic link-clicker would find their way to this or that page.
While this is no longer nearly as prominent as it once was as a ranking factor (or as a full-court SEO strategy), it is still the case that a site with great internal linking supports both findability onpage and findability on search. The prominence, placement, quantity, and quality of internal links to your pages – the ease of locating pages by navigating onpage, rather than by engaging a search function – can have a major effect on pages’ likelihood to be ranked for relevant queries on search. As is often the case, much of what goes in to SEO in fact supports logical, intuitive web structures and human-centered customer experiences (often through declining to respond to “optimizations” that bring little value to the customer).
You may have information control issues (if you’re not watching your search data)
SEO can also help point up gaps in your ability to serve customers information they are looking for. I recommend looking for branded (or product) queries for which your property isn’t ranking. If you find that others are answering questions your users may have on forums, or have published code dealing with an issue you haven’t published on – you are likely to encounter some meaningful issues in terms of information quality.
If you are monitoring internal search, you may find that there are queries and intents for which your docs pages aren’t providing real value. Smart search engines like Coveo or Algolia can improve the internal search experience, but not your internal information quality as reflected on existing pages. I think complementing evidence of a technical content gap (which exists offpage) with evidence of unsatisfied customer intents (which you can adduce from both internal and offpage data) is a powerful lens through which to refocus your narrative around documentation away form information-idling and towards business needs.