DITA Technical Documentation and SEO

The "Hide a Dead Body" SEO Joke

I will be covering all of the points in this article and more in a webinar presentation on DITA and SEO at CIDM’s online IDEAS Summer Online Conference on July 25, 2017. I hope to see you there!

There’s a joke making the rounds that goes like this: where is the best place to hide a dead body? Answer: on the second page of a Google search result. The joke underscores the serious business of search engine optimization (SEO), the half-art/half-science discipline whose goal is to increase traffic to a web site by seeking improved search engine rankings on the major search engines such as Google, Yahoo!, and Bing. In most cases, SEO for a company’s technical documentation is an afterthought, if it is even thought of at all. Technical documentation is part of the digital and social media landscape, and there is evidence that would-be purchasers will look at and assess the quality of a product’s documentation prior to buying a product. The after-purchase experience is also important, as users may have a need for product documentation when seeking more information on a particular function or trying to solve a problem. So if users can’t find your documentation, it is a lost opportunity to engage with them. While there are some distinct SEO strategies for DITA documentation, the best thing you can do is to know your audience and write for them, as effective SEO for technical documentation is all about directing users to relevant content rather than click-bait “tricks”.

What is Important to Google?
From a search engine’s perspective, there are many factors that come into play when assessing the relevancy of content, but not all of these are things that a typical technical documentation department has control over. I have found a useful summary of SEO factors listed in this article, and it includes factors relating to the domain name under which content is posted, page loading speed, the website’s architecture, server location, the type of security certification being used (if any), and many other factors in which technical writers usually have no say. While it is good to know about these other factors, this piece concentrates on aspects of technical writing SEO that are under a DITA-using technical writer’s control.

Here are four key things that DITA-using technical writers should keep in mind in terms of technical documentation SEO:

  • Write descriptive titles
  • Add internal links using relationship tables
  • Well-written short descriptions inform your users what your topic is about before they read it, leading to more click-throughs
  • Know your audience and create content that meets their needs.

How Descriptive Titles Can Help with SEO
Content associated with the initial title element of a DITA topic is expressed by the DITA-OT in HTML output within the header of a webpage. In fact, it is expressed twice: as an equivalent XHTML title element and as a Dublin Core counterpart (“DC.Title”). The title of any webpage is—in most cases—used as the default search result link to a webpage. This is where DITA best practices comes into play; avoid using boilerplate titles for your topics (“Introduction”), and instead make them descriptive (“What You Need to Know About the Vebulon 5”). Also, do not overload them with keywords (“All About the Vebulon 5 – Vebulon Five, Fifth Vebulon, vebulon five, 5th vebulon, vebulon the fifth, Acme Corporation’s Vebulon Five”). Not only will this be seen as a ruse to improve ranking using keywords and drive the SEO for that webpage down, but also it is likely to be confusing to a reader viewing the link. Finally, make your titles concise: Google truncates long titles that are over 70 characters long.

Short Descriptions and SEO
From an SEO standpoint, effective short descriptions are also important. The shortdesc element is used to contain a short description for a topic within DITA, and the DITA-OT outputs this as description metadata in the header of an XHTML webpage. When present, short descriptions are displayed immediately below the title link of a search result webpage on the search engine.

It is also worth knowing that a search engine may also automatically truncate lengthy short descriptions. While DITA short description best practices suggest two full sentences, know that Google truncates lengthy short descriptions that are over 156 characters. While short descriptions are not directly factored as part of the search engine rankings for a webpage, user behaviours are. Google, for example, measures click-through rates (CTR), so a well-written, descriptive short description will ensure more click-throughs as users get a better sense as to how a DITA topic can help them. A well-written short description tells the would-be reader on the search engine results page why the page link is worth clicking on. So don’t simply reiterate the title, instead tell your users what they can accomplish once they have read the topic.

Creating Internal Links by Using Relationship Tables
Another metric known to influence webpage ranking is the number of links to a page. More weight is applied from external URLs pointing to a webpage than internal ones, but internal links to and from pages within your documentation counts as well. DITA has a nice built-in solution for this: relationship tables. The trick here is not to go overboard, but to emphasize topics within a relationship table that are critical for understanding and working with the subject of your content. Adding relationship tables to DITA content is considered a DITA best practice, and it may also prove to add to SEO as well.

Having effective titles, useful short descriptions, and properly implementing relationship tables are all ways that you can enhance the SEO of your DITA-based technical content. Even better, they all emphasize DITA best practices, so this is a win-win situation both for your documentation and for your users. While these techniques are worth knowing, it became evident to me that the more you can effectively engage with your audience—providing them with the information they need when and where they need it—the better your content will do in terms of SEO.

Write to Engage Your Audience
Many SEO-oriented websites talk about how to “trick” the likes of Google (which, let’s face it, is probably the dumbest thing you can do), but from a technical writing perspective I would argue that it is really all about knowing your audience, being honest with them, and ensuring that you deliver relevant content. If information is poorly described or not targeted to the right audience, users will not find it. It’s that simple.

This brings us back to some of the first principles of Content Strategy:

  • Know your users!
  • Why have they come to your content?
  • What are they seeking to accomplish?

A content strategy that includes having personas and scenarios to guide your technical writers should be a priority, as it can guide them in the creation of effective documentation fitting the needs of your users. The more technical writers come to understand who their users are and the circumstances that are likely to bring them to your documentation, the better the SEO will be for individual webpages, because relevant content rises to the top in searches.

Another DITA best practice that comes into play in terms of writing effective content is minimalism. Meet the needs of your users as concisely as possible. Major search engines like Google have invested significant resources into parsing human language requests, so consider phrasing your DITA topics to answer a query. Keep in mind that DITA and its topic types can help shape the dialog between technical writers and their audience:

  • Task: how do I accomplish this procedure?
  • Concept: what is this thing and what is it for?
  • Reference: what are the correct settings?
  • Troubleshooting: how do I fix this problem I am having?

If technical writers can answer these questions for the particular scenarios in which users are likely to ask them, the content will be more relevant and will naturally rise in search engine rankings. I would also urge people not to think in terms of SEO “tricks”; the best thing you can do is to know your audience and write for them and their needs. Effective and SEO rewards those who choose to engage with their customers rather than trying to fool search engines with cheap ploys.


"DITAWriter" is Keith Schengili-Roberts. I work for IXIASOFT as a DITA Specialist/Information Architect. And I like to write about DITA and the technical writing community. To get ahold of me you can email me at: keith@ditawriter.com.

View all posts by