The searchtitle element

You know the feeling: after a busy afternoon of researching and bookmarking the documentation for a product you just bought, you go back to look for the particular link you logged about installing on weekends. But all the bookmark titles just say “Installing FooFram” with no other clue about that weekend issue. Whoever wrote those chapters needed searchtitle for the web version of that document!

The general point is that if a particular topic title is too long for use in an online table of contents, use navtitle to suggest a shorter version for the processing tools to use for the navigation title. And if the topic title is too abrupt for users who might see it in a bookmark or in search results, use searchtitle to provide more context for that case.

Did you know?

The current DITA 1.2 Spec enigmatically says that a searchtitle “should be displayed by search tools that locate the topic.” This is actually a result of the search process, not a direct effect of building a topic that has a searchtitle. The story behind that statement is that when a DITA topic is built into a standalone Web page, the transforms commonly use the searchtitle content, if available, as the content of that page’s title element. Search engines use this title rather than headings in the body of the document to build their search summaries. Hence, the searchtitle IS what you see whenever a search brings up its link to an HTML topic that was generated from DITA. It wasn’t meant to be confusing; we just managed to make it that way for you!

Now, because this searchtitle is so darned important to search engines, you should use care in creating just the right wording for it. As you can imagine, any advice for writing a good HTML title tag applies to writing a good DITA searchtitle as well. I’ve listed an example of such a guide. Check your organization’s writing guidelines to see if there are particular web publishing goals for the HTML title tag (and by implication the DITA searchtitle element).

If you leave off the searchtitle, output transforms will generate one for you, generally from the topic’s title. And just as with the “Installing FooFram” example, this may be less than optimal for what someone doing a search may expect to find!

Deep Dive

Leave a Reply

Your email address will not be published. Required fields are marked *