The issue is this:
When a body of material (topic) only ever appears in one context (a book), and everything around it relates to the same thing, then putting the product name in the title is obviously redundant. But when looking for topics, there is no surrounding context for search results. In that case, you need more information about the context that the topic was intended for.For example, imagine this in a book about the XYZ product:
Chapter 1: Using the XYZ
Logging in to the XYZ
Using the XYZ Dashboard
Managing Users in XYZ
Seems massively redundant, right? So you naturally simplify your topic headings (Logging In, Using the Dashboard, etc.)But now imagine that you’re searching for topics to reuse, and what you see is “Using the Dashboard”. Heck, that sounds like something you could use. Except that it doesn’t apply to anything but XYZ, and you may have to read the topic closely to find it out.
I just had a similar situation with a new topic sent my way. It described a series of commands for creating instances of things that the product I'm writing about happens to use. But it turns out that my product is doing all that automatically, behind the scenes, so this topic was only pertinent for a particular product--and the title didn't tell me that.
Fortunately, the topic's author knew enough to tell me that. But if she were unavailable, and I was just browsing, it would have been hard to tell.
That’s why, in some installations, topic titles are supposed to include product, version, and darn near everything else necessary to identify the context in which that topic fits.
Now then, as with all things DITA, there are multiple ways to do things. We have:
- Navtitles in maps
- Navtitles in topics
- Topic titles
- Search titles in topics
The navtitle should, by rights, be used in printed TOCs and online PDF TOCs. The idea is to provide the short, non-redundant title that you would expect in any particular context. (I like the idea of attaching them to the topic. But they never seemed to show up in any of the outputs we've been generating, so navtitles in the map became my default.)
That leaves topic titles and search title. The idea of search title is that you can provide lots of detailed context info like product and version, and search tools like those provided by a CMS will display that title when you do a search, so you can see the exact context for which that topic was intended, without bothering the reader with that information.
But things get really dicey when you start publishing things to the Web. At some point, you wind up with multiple copies of "Using XYZ"--one for each version of the product that got released. When someone asks a search engine, "how do I use XYZ" they're going to get back three almost-identical pages, unless the title includes a version number. (And if it doesn't include the product, some search engines may not find it at all!)
At the moment, then, my best guess is that these combinations seem to be the most reasonable.
- Simple navtitles and relatively complete topic titles (assuming that the output processing can be persuaded to do the right thing with the navtitle)
- Simple topic titles and totally complete search titles (given a CMS)
Since I have yet to work at an installation that has a CMS, I just automatically go to option “A”, on the assumption that the output processors will eventually get whipped into shape.
But I wonder what others think...

No comments:
Post a Comment