Maps in DITA

The basic DITA map concept is extremely generic; maps are how you arrange topics into a structure. Maps are all structure, and no content, though they may have meta-data. The "all structure" part can be one of the tougher parts of the mental transition to topic-based authoring.

Simple XML

The XML for a topic reference in a map is simple

<topicref href="topic_UID" type="task" />

to reference a single topic, and the topicref element nests, so you can produce tree structures:

<topicref type="topic" href="Intro_UID">
  <topicref type="concept" href="Subject1_UID">
    <topicref type="task" href="Subject1_Task1_UID" />
    <topicref type="task" href="Subject1_Task2_UID" />
    <topicref type="reference" href="Subject1_ChartsAndTables_UID" />
  </topicref>
  <topicref type="concept" href="Subject2_UID">
    <topicref type="task" href="Subject2_Task2_UID" />
    <topicref type="task" href="Subject2_Task2_UID" />
    <topicref type="reference" href="Subject2_TopographicMap_UID" />
  </topicref>
</topicref>



but the implications aren't as simple as the XML.

A Topic Doesn't Care Who Is Pointing at It

A good topic is independent of the topics around it. You can mix and match units of information to create the document you want for a particular purpose. Therefore, when topics are organized together by a map, the information about any group of topics—what it's for, why it's a group, who might want to read it, how you should approach reading it, what scenario is addressed by this particular sequence of topics—is not going to be contained in the component topics of the arrangement. So you need a way to provide this map structure description, contextual information linked to the specific map (the specific arrangement of topics).

Good topics do not know what maps, if any, reference them; it could be one map, no maps, or eleven thousand maps, and this should make no difference to the topic as a content object.

Map structure description is not independent of the structure of the map; it cannot be arbitrarily re-arranged or referenced by other maps. It is therefore not suitable for being delivered as a topic content object.

One solution to the problem of providing map structure description is to use unspecialized topics—the Intro_UID topic in the example above—to contain information about topic groupings. (The most basic information-causes change type of information involved in map structure description answers do I need to read this? for each known audience type you are addressing.)

This nest-in-generic-topics approach has the twin drawbacks of a) making it difficult to separate the topics that are the content objects and the topics that are map structure description in your CMS search system and b) introducing a considerable risk of natural language dependency between topics. Introducing natural language dependency is especially difficult to avoid early in the transition to topic-based authoring when it will remain conceptually easier to stick some informational content in the map structure description. This is the sort of topic-interdependence that hampers re-use and makes you have to know about the specific natural language content of a topic before you can use it in another map.

Ideally, some combination of good writing discipline, the content management system, and DITA specializations will prevent an outcome where map structure description takes on information content and hinders content object independence for topics and ease of topic re-use.

In terms of the CMS and DITA specializations, it is especially desirable to restrict topic content object references—the actual content — to being leaves, and only leaves, of the tree structure represented by the DITA map XML document. If this is the case, natural language dependencies between topics, including specialized topics used to provide map structure description, are almost impossible to introduce by accident, ease of re-use is maintained, and you can't get into structural trouble with map-in-map references.

[Subhead]Alternative approaches to providing map structure[/Subhead]
(Not an exhaustive list)

• specializing one or more map types so that they can contain their own structure description
• using the short description—<shortdesc/>—element of a topicmeta element in the map to contain the map structure description
• specializing a restricted topic type that functions strictly as map structure description
• accepting that you won't provide map structure description (which tends to raise fewer aesthetic issues in an HTML delivered document context than it does in a PDF or print delivered document context)
• automatically constructing map structure descriptions from the map's child topics
  
  • having the output processing pull the navtitle and the short description of each child topic, for instance
  • this approach requires extremely disciplined and consistent topic writing
  • no special-case topic types or map specialization

Map structure description is an issue your information architect and editors need to be on top of before anybody gets confused about it. This is one of the truly different things about topic-based authoring, compared to narrative authoring, and clear communication throughout the writing team is a big help with making that part of the transition go smoothly.

Maps of Maps ... of Maps!

Maps represent, and can contain, more than one type of structure. For instance, and non-exhaustively, maps can group topics as:

• a table of contents hierarchy
• the fulfilment of a particular scenario for a particular persona in scenario-based authoring
• a collection of thematically related information, such as a group of topics covering the safety precautions or operating requirements of a particular product

It is very important when selecting a content management system that you select one which fully supports all the types of grouping you want to be able to do with maps. While it's entirely possible to manage maps by hand, with human beings either typing or cut-and-pasting object ID references like href="gra1205267857891.xml", it's not really practical. You want select-from-search, drag-and-drop means to assemble your topics into maps, and a display mechanism for the assembled maps that both shows the primary tree structure and presents topics in terms of something human-readable, like their title and type.

DITA maps Can Be More Complex Than a Simple Hierarchy of References

One of the most useful additional map components is the DITA reltable element—relationship table—which can be used to define relationships between topics in the map other than the hierarchical, table-of-contents relationship of the main map structure. You can use these relationships to provide secondary information traversals for the content referenced by a map, such as those which fulfil particular scenarios for specific personae in your target audience.

In this application, the main, table-of-contents ordering is provided by the map structure and specific, persona-targeted information traversals associated with individual scenarios are provided by the relationship table element. This requires that you have output processing that can interpret relationship tables in this way. You'll either have to build that yourself or get your CMS vendor to do it. Hand-editing relationship tables is even less of a source of joy than hand-editing regular XML tables, so you also want to make sure you XML editor or CMS provide support for building relationship tables before you set out to use this approach in a production environment.

Divide and Conquer

When managing large maps—it's really easy to have a 500 topic map if you're providing a comprehensive user guide for a medium-sized software application—it can be much, much simpler to treat some or all of the main, represents-the-content-delivery map as a grouping of smaller maps.

Since DITA 1.1, map-in-map references are a standard part of DITA. The only (very slightly) confusing thing about this

<topicref href="map_UID" format="ditamap"></topicref>

is that it uses the topicref element, and distinguishes map references for processing by use of the format attribute.

One implication of map-in-map structures is that you can standardize a component map type, and use that map type to build the maps that correspond to a full content delivery.

It's very likely you will have emergent patterns in your maps; similar information being presented to similar audiences will be, or at least ought to be, expressed in similar ways.

An example of this kind of pattern is a standard lesson pattern where you have

• a concept topic (the subject in the abstract as an aide-mémoire for the instructor)
• one or more task topics (what the instructor is to do to deliver the lesson)
• one or more reference topics (supplementary information, such as bibliography or references for further reading)

Once you have identified these patterns in your content, you can create named template versions of your component map type to match the pattern. This facilitates both consistent patterns of information presentation and ease of large map construction. It's significantly easier to manage the main map has seven lessons in it and seven individual lesson-pattern maps than it is to manage one large map which references all the topics directly. Because the map inclusion is by reference, the component maps can become larger units of re-use; every installation guide gets the component map on ensuring you have a safe work area, for example, or every software manual gets the component map about how to contact the company, what the warranty is, and so on.

Maps, or at least the content delivery maps, have associated due dates, and anything with a due date has, or really ought to have, someone responsible for making sure it meets that date. This means that you should consider associating the due date and the map lead—the person responsible for making sure this map meets that due date—with the map as meta-data in your CMS. Once you've done that, you can include other role-related meta-data like a list of approving stakeholders or who the assigned editor is for this map.

Maps then function as:

• hierarchical table-of-contents organization for topics
• secondary, fulfils-a-scenario organization for topics
• hierarchical, table-of-contents organization of other maps
• templates for repeated patterns of topics in the content delivery
• a unit of assignment, through CMS meta-data giving due dates and assigning responsibility for completion