DITA and SEO DITA AND SEO. Keith Schengili-Roberts, IXIASOFT

Size: px

Start display at page:

Download "DITA and SEO DITA AND SEO. Keith Schengili-Roberts, IXIASOFT"

Sara Wilkerson
5 years ago
Views:

DITA and SEO Keith Schengili-Roberts, IXIASOFT Keith Schengili-Roberts IXIASOFT Keith Schengili-Roberts is a DITA Specialist at IXIASOFT, DITA evangelist and an awardwinning lecturer on Information

1 DITA and SEO Keith Schengili-Roberts, IXIASOFT Keith Schengili-Roberts IXIASOFT Keith Schengili-Roberts is a DITA Specialist at IXIASOFT, DITA evangelist and an awardwinning lecturer on Information Architecture at the University of Toronto. His popular industry blog DITAWriter.com has become a focal point on DITA resources and best practices. Connect with Keith on KeithIXIASOFT. 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. There are digital agencies out there whose raison d'être is to increase SEO for their client companies, but this focus is almost always for a company s marketing materials. In many 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 sometimes 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. But 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 more about content relevancy than tricks. But First, a Story What made me first think of the subject of SEO and technical documentation was an incident that happened to me a few years ago when our washing machine stopped working in the middle of a cycle, filled with water. This happened late on a Sunday afternoon, so there was little to no chance of calling a repairperson to come and look at it immediately. Our family has two teenage girls, and let s just say we couldn t be without a working washing machine for too long. I Googled the washing machine manufacturer s name along with the phrase: not draining. What came up first were some YouTube videos, followed by handy tips provided by both users and professionals. In the end, the first result that came up was a video that provided me with all of the information I needed to know: a busted lid switch was the source of the problem. I used the information from the video to fix things enough to get the machine working again. When I called a repairperson the following day, I was able to not only tell him what the specific problem was, but also the replacement part number he needed to bring. As of June 2016, that video I found on YouTube has been viewed over 200,000 times; remember that this is a video about a broken washing machine with a very specific problem. I have worked in the technical documentation field for over a quarter-century, and I was curious to see whether or not the manual for the washing machine would turn up if I continued my search on the problem I encountered. After scanning through 10 more pages of search results on Google, I gave up. I did a different search looking specifically for the manual for the machine and then looked within it to see if it had a solution to my problem. To give the manufacturer (and their tech docs team) credit, the problem I ran into was described in the troubleshooting section of the manual. The correct solution to my problem was not. While it s likely that the manual was not updated significantly since the launch of the product, not providing the correct information on what was clearly a common problem (remember those 200K views for the YouTube video?) was definitely a lost opportunity for that manufacturer to effectively engage with their users. Wanting to learn more, I began to investigate the murky world of SEO from a technical documentation and DITA perspective. 88

2 Understanding How Search Engines Work To better understand SEO, you first need to know how search engines work. Whether it is Google, Bing, or Yahoo!, they all share a common process that can be broken down into three separate phases: spidering content, indexing it, and then providing that information on demand to users who query the search engine. Before enhancing the SEO of your technical content, you first need to ask whether or not you want to do so in the first place. While most companies will want their technical content findable on major search engines, there are scenarios where this is not desirable. For example, a company may want the search engines to favour results from their marketing material over their technical content. Or a company may have its own search engine designed specifically for technical content and want to direct their users to use the company s own customized and specialized search experience. In these instances, you can simply tell the search engine spiders not to index a page or set of pages. There are two ways to accomplish this: through adding a metadata value to your webpages or by using robots.txt. To exclude an individual webpage from being indexed by any search engine, simply add the following in the header: <meta name="robots" content="noindex"/> The only downside of this approach is that this only works on a page-by-page level. To exclude a specific directory full of technical content from being indexed use robots.txt instead. To disallow a spider from crawling all of the content in the /tech-docs/sub-directory on your webserver, you upload a robots.txt file containing the following content: User-agent: * Disallow: /tech-docs/ This text basically tells the spider (which is the user-agent in this case) to ignore everything contained in the /tech-docs/ folder. Google Webmasters has good information on how to add more specific noindex metadata to your webpages available at com/webmasters/answer/93710?rd=1. For more detailed information on how to customize a robots.txt file, see: If on the other hand you want to draw web spiders to your technical content webpages, you can assist them by providing them with a sitemap.xml file. This file neatly encapsulates what information is available, and it contains the following information: The parent URL for the web site The URL of a specific page The date that webpage was last updated (optional) How frequently the page is likely to change (optional), and The priority of a given page in comparison to other pages on the web site (optional) If you opt for an application to automatically create this for you, by default it will create a file that assigns a high priority value to the top-most webpages in your technical content hierarchy, and then provides progressively lower values for pages further down. You can tweak this priority value to increase the likelihood of your most important pages being present in a search result. The priority value ranges from 0.0 to 1.0, with the highest value being 1.0. Before you set the priority of all your technical content webpages to 1.0, know that if you set a high priority to everything, the priority value will be discounted and averaged out by the search engines, so tweak the priority values judiciously. For more information on this XML format and how to use it effectively, see The Relevance of Metadata from an SEO Perspective Metadata can be embedded within DITA maps and topics which can then be expressed by the DITA Open Toolkit (DITA-OT) as equivalent XHTML metadata when that content is outputted. From an SEO perspective though, not all metadata is equal. 89

Within DITA, metadata is added to bookmaps using the bookmeta element and to the prolog of individual topics.

3 Depending on which metadata is added to the original DITA content, the DITA-OT produces equivalent metadata for XHTML. Not all of this metadata is actually used by the major search engines, but it is good for authors to know about the DITA-to-XHTML relationships that are currently available. Within DITA, metadata is added to bookmaps using the bookmeta element and to the prolog of individual topics. Metadata content within DITA is then expressed in XHTML output primarily as Dublin Core metadata. What is Dublin Core? It is a set of metadata designed to semantically describe web content. Since the mid 2000s, the Dublin Core Metadata Initiative organization has worked with the World Wide Web Consortium the standards body responsible for HTML and the HTTP protocol towards this goal. The DITA-OT uses a subset of Simple Dublin Core v1.1 when outputting to XHTML, so when you add metadata to your DITA maps and topics, it is expressed at output as Dublin Core. The illustration in Figure 1 shows how DITA metadata within a topic is converted by the DITA-OT to its Dublin Core equivalents. For reference, Table 1 describes DITA metadata and its Dublin Core equivalent at output. Figure 1: DITA Topic Metadata and its Equivalent XHTML Output in Dublin Core Table 1: DITA map and topic elements and their equivalents in Dublin Core XHTML Output from the DITA-OT 90

Figure 2: DITA Keyword Metadata and its Expression in XHTML While Dublin Core is long established and has support from the broader web-based community, Google and the other major search engines do

4 Figure 2: DITA Keyword Metadata and its Expression in XHTML While Dublin Core is long established and has support from the broader web-based community, Google and the other major search engines do not appear to do much with this. Having the Dublin Core Metadata available can be advantageous from a web content management perspective, as a WCMS can pull Dublin Core values from webpages and use them for providing a faceted search, for example. But from an SEO perspective, Dublin Core is not the answer. The relevance of keyword metadata and SEO is also worth mentioning. In the early days of SEO, a common strategy was to load up a webpage with keywords. There is a mechanism in DITA for incorporating them by using the keyword element, and the DITA-OT dutifully expresses this information both as Dublin Core and as keywords metadata in the header of an XHTML webpage, as Figure 2 shows. Sadly, this is yet another technique not recognized from an SEO standpoint. Google has gone on record as saying that they do not use the keywords metatag in their web ranking algorithm, as it was too often stuffed with irrelevant information and was subject to abuse. So are there any good metadata practices that can be used from a DITA perspective? Yes, and what s more, they fit nicely with DITA best practices for writing effective topics. What is Important to Google? From a metadata perspective, there are two things that search engines like Google make use of: the title and short description of a webpage. It is also important to understand that SEO is not a passive process, as search engines keep track of information that users click on. Creating an effective internal hierarchy of content may also play a role in SEO, and DITA s relationship tables may help in this area. And last but far from least, know your users and tailor your technical content to their needs. Content associated with the initial title element of a DITA topic is expressed by the DITA-OT in 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 web page. 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 it is likely to be confusing to a reader viewing the link. Finally, make your titles concise: Google truncates long titles that are over characters long. 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, as Figure 3 shows. 91

Figure 3: An example as to how a short description is used to describe a webpage within a search engine This example also nicely illustrates how a lengthy short description may be automatically

5 Figure 3: An example as to how a short description is used to describe a webpage within a search engine This example also nicely illustrates how a lengthy short description may be automatically truncated by the search engine. While DITA short description best practices suggest two full sentences, Google truncates this in its search results to about 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. Again, this fits well with DITA best practices for short descriptions. A wellwritten short description tells the would-be reader on the search engine results page why the page link is worth clicking on. Per topic type, here s what your short description should aim for: Task: tell users what they can accomplish Concept: tell users about what you are describing and why they should care Reference: tell users what the referenced item does or what it can be used for Troubleshooting: describe the symptoms of a problem a user may encounter and let them know that this topic can help So don t simply reiterate the title, instead tell your users what they can accomplish once they have read the topic. Another metric thought 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 an internal hierarchy 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. 92

6 Write to Engage Your Audience Many SEO-oriented web sites talk about how to trick the likes of Google (which, let s face it, is probably not the best approach), 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 you think back to the original washing machine example, it is clear that they were not anticipating the needs of their users adequately, leaving open a content hole that a video creator on YouTube was able to fill. And while the problem that arose may not have been anticipated prior to the publication of the original manual, a subsequent edition definitely could have addressed it. Ultimately the manufacturer passed up an opportunity to engage with its users, potentially hurting its brand. This example underscores how important it is to anticipate users needs and to address them in the technical documentation. 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 is why 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. Consider again the case of the broken washing machine. It has a section in its documentation on troubleshooting, that combined the particular problem I encountered with a Won t Drain/Won t Spin/Wet Load section. This is relatively close to what I entered into the search engine when I looked up [product name] not draining, but the original title is not phrased in a way that is likely to come up in an online search. There was no short description in the original troubleshooting documentation, and it did not address the specific problem I ran into. When you put all of this together, it is no wonder that the original technical documentation was ranked as poorly as it was by the search engine. 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: Concept: what is this thing and what is it for? Reference: what are the correct settings? Task: how do I accomplish this procedure? 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. Summing Up You now have a basis for better optimizing your DITA technical content for search engines and users seeking information. Making your content relevant to your users is a win-win situation, as your users find the information they need when and where they need it. Effective, concise titles and short descriptions will generate more clickthroughs by users, which in turn will aid with search engine ranking of your technical content. You can also tweak things by adding a sitemap.xml to help spiders find and index your content, and effective use of relationship tables may also help search engines determine what information you consider important for users to know. The use of metadata in your content is far from useless, but knowing what to concentrate on is half the battle. Finally, I would 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. Effective and long-term SEO rewards those who choose to engage with their customers rather than trying to trick search engines with cheap ploys. 93

How To Construct A Keyword Strategy?

How To Construct A Keyword Strategy? Introduction The moment you think about marketing these days the first thing that pops up in your mind is to go online. Why is there a heck about marketing your business online? Why is it so drastically