- Andrew Huff / Foter / CC BY-NC
Among the cards you carry with you daily, you are likely to have credit cards, loyalty cards, insurance and library cards, and more. Each one is associated by your name or other identifier to a member profile in a database. Besides your unique identifier, each profile of yours also records your level or role of membership in a group, your address, possibly some value or role that you represent to the respective group, among other data. A profile is a unique member record that describes how you relate to other members and to the group itself. You are a resource, and the profile is your resource description. And like a profile, a topicref is also a resource description. What kind of resource? Well, don’t let the name fool you. Topicref is DITA’s most versatile element!
Despite its name, the topicref element is not only a reference to a topic. A topicref can represent any kind of resource, including a PDF, an HTML or Markdown file, or even other lists of pointers. In conventional DITA use, a topicref usually describes a DITA topic resource. During a build, a topicref represents several roles: first, it represents inclusion of a resource for a particular deliverable, and second, it represents a link to a resource. Mathematicians would observe that a topicref is implicitly an arc to a node in a graph. In this regard, a topicref is literally generic enough to describe any kind of resource as a “member profile”–something you can query to learn what you need to know in order to make some use of it (a clear example of which is to access a Markdown file to transform into a DITA topic for building into a DITA Open Toolkit deliverable).
In many respects, a collection of DITA topicrefs is similar to a Google sitemap. In the Google design, values are represented as child elements versus the use of attributes in topicref. In terms of information, there is little difference between the two forms of syntax; both versions serve as islands of profile information about a resource at a particular location.
In practice, there is more flexibility in using topicrefs in the DITA map structure to represent particular kinds of processing that you may wish to apply to the values. Sitemaps have only one common use–to inform search tools of the current state and availability of searchable targets–whereas DITA maps are a popular publishing standard that supports multiple uses. A DITA map that defines the content of a microsite is completely transformable into a sitemap.
Did you know?
One of the more interesting things I have done with a “ditamap as sitemap” is to represent the entire content definition of a microsite as a content instance that can be alternately represented as a white paper or brochure (DITA maps and treemapping–birds of a leaf). In this usage, the first-level topicrefs in a content hierarchy represent the primary tabs of a web site, and the child topicrefs represent the pull-down menus. This is actually a useful serialization of the usual data structures that normally define the salient navigation experience of web sites.
Is this use better than usual deep arrays of data values that define most site navigation? In practice, the two methods offer equivalent capabilities, but the data arrays are certainly the more common, baked-in behavior of many Web publishing tools. If you need to publish a web site, you will likely be using XML-based tools for creating the necessary result view and link resolution, so even a programmatic conversion of the nav arrays into a DITA map provides a useful entry point to the publishing process itself.
I’ll note that at the time of my experimentation in 2010, I was using maps to represent the site layout as well as the content organization. This involved literally rebuilding all the site content for each view, which is obviously not efficient. But academically interesting, yes!, because now I have that example as an extreme endpoint for the range of things you can do with adaptive content.
Another potentially useful aspect in the full capabilities of the topicref element is its “query” attribute. The “href” attribute normally encodes the full path to an absolute resource. In terms of RESTful URI design, @href holds the RESTful path while @query represents a Remote Procedure Call or parameter query form of addressing. Content in CMSs for example often exists in multiple versions that are usually added to a URL as “?version=2.4.1&status=published” or the like. Obviously the RESTful href name is the predominant access method out there. But where content exists in a CMS and may have a number of different access points depending on workflow needs, I am using this bully pulpit to again bring it to attention as an artifact that was never in a primary role, but might in fact have a key role for the CGI domain of content retrieval, which is not dead but lives quite healthily in the heart of applications rather than in the published content realm.
Deep Dive
- DITA 1.2 Spec: The topicref element
- How to create a site structure Google will love, an interesting discussion of the use of search strategies to refine the structure of resources at a site.
- Website Structure Understanding and its Applications. This research study is interesting as a response to “What do you do with the results of a Content Audit?” Their advice is to restructure the site to bring resources with the best value into a structured relationship with other resources. The closing discussion on structured data sets applies well to information architectures using structured resources on the Web, whether DITA, Markdown, or other units that can be described by topicref.
- The XML Bookmark Exchange Language (XBEL) is worth reexamination as a DITA map/topicref application, in light of its role as a collection of resource profiles.