How to define a formal information architecture with DITA map domains

Formal information architecture

Information architecture can be summarized as the design discipline that organizes information and its navigation so an audience can acquire knowledge easily and efficiently. For instance, the information architecture of a web site often provides a hierarchy of web pages for drilling down from general to detailed information, different types of web pages for different purposes such as news and documentation, and so on.

An information architecture is subliminal when it works well. The lack of information architecture is glaring when it works poorly. The user cannot find information or, even worse, cannot recognize or assimilate information when by chance it is encountered. You probably have experience with websites that are poorly organized or uneven in their approach, so that conventions learned in part of the website have no application elsewhere. Extracting knowledge from such information resources is exhausting, and you quickly abandon the effort and seek the information elsewhere.

Currently, information architects work by defining the architecture through guidelines and instructions to the writer. A better approach is to formalize the architecture through an XML design that is validated by the XML editor or parser. This formal approach has the following benefits:

Authors receive guidance from the markup while working.
Information with the same purpose is consistent across deliverables.
Information for a purpose is complete.
Processing can rely on the structure of the information and operate on the declared semantics of the information.

The following drawings illustrate the gain in clarity and consistency by applying a design to produce a formal information architecture:

Casual architecture	Applied design	Formal architecture

In short, the formal design acts as a kind of blueprint to be fullfilled by the writer.

Specializing topics and maps

DITA supports the definition of a formal information architecture through topics and map types. The topic type defines the information architecture within topics (the micro level) while the map type defines the information architecture across topics (the macro level).

The base topic and map types are general and flexible so they can accomodate a wide variety of readable information. You specialize these general types to define the restricted types required for your information architecture.

Topic: The topic type mandates the structure for the content of a topic. For instance, the DITA distribution includes a task type that mandates a list of steps as part of the topic content. This specialized topic type provides guidance to the author and ensures the consistency of all task topics. Processing can rely on this consistency and semantic precision. For instance, the processing for the task type could format the task steps as checkable boxes.
Map: The map type mandates the structure for a collection of topics. A map can define the navigation hierarchy for a help system or the sequence and nesting of topics in a book. For instance, the DITA distribution includes a bookmap demo that mandates a sequence of preface, chapter, and appendix roles for the top-level topics. This specialized map type ensures that the collection of topics conforms to a basic book structure.

Without formal types, the information architecture is defined only through editorial guidelines. Different authors may interpret or conform to the guidelines in varying degrees, resulting in inconsistency and impredictability. By contrast, the formal types ensure that the design that can be repeated for many deliverables.

The how-to collection

One typical purpose for a collection of topics is explain how to accomplish a specific goal. A how-to assembles the relevant topics and arranges them in a typical sequence for one way to reach that goal. A standard design pattern for the how-to collection might consist of an introduction topic, some background concepts, some task and example topics, and a summary.

A help system or book might have several how-tos, for instance, on setting up web authentication, reading a database from a web application, and so on. Or, a web provider might publish an ongoing series of how-to articles on technical subjects. Thus, designing a formal how-to pattern would be useful so that all how-tos are consistent regardless of the writer.

Note that formalizing a collection doesn't prevent topic reuse but, instead, guides topic reuse so that appropriate types of topics are used at positions within the collection. For example, in the how-to, concept topics will appear only as background before the tasks rather than in the middle of the how-to.

Map specialization

Among the many capabilities added to maps by DITA 1.3 is specialization through map domains. Instead of packaging specializations of elements for topic content, however, you specialize elements for map content, typically thetopicref. The specialized topicrefelement lets authors specify semantics or constraints on collections of topics. By packaging the topicref specializations as a map domain rather than as a map type, you can reuse the formal collection design in many different map types.

A specialized topicrefcan be used for the following purposes:

To restrict the references to topics of a specialized type. For instance, a conceptref refers only to concept topics (including specialized concepts).
To assign a topic a topic to a role within a collection. For instance, the topic identified by a summaryref could provide the concluding explanation for a collection.
To restrict the contents of the collection, requiring specific topic types or requiring topics to act in specific roles at specified positions within the collection.

Drawing on all of these capabilities, we can define a formal structure for a how-to collection.

Implementing a map domain

A map domain uses the same DTD design pattern as a topic domain. See specializing domains for the details on the domain design pattern, which aren't repeated here. Instead, this article summarizes the application of the domain DTD design pattern to maps.

Create a domain entities file to declare the elements extending the topicref element.
Create a domain definition module to define the elements including their element entities, content and attribute definitions, and the architectural class attribute.
Create a shell DTD that assembles the base map module and the domain entities file and definition module.
Create map collections from the shell DTD.

Declaring the map domain entities

The entities file for the how-to domain defines the howto, conceptref, taskref, and exampleref extensions for the topicref element and defines the how-to domain declaration for the domain attributes entity:

<!ENTITY % howto-d-topicref "howto">
<!ENTITY howto-d-att "(map howto-d)">

Defining the map domain module

The definition module for the how-to domain starts with the element entities so the new elements could, in turn, be extended by subsequent specializations. Of these new elements, only howto has been declared in the entities file because the other new elements should only appear in the child list of the howto element. (In fact, reference typing elements such as conceptref and taskref might also be defined in the entities file for reuse in other specialized child lists.)

<!ENTITY % howto       "howto">
<!ENTITY % conceptref  "conceptref">
<!ENTITY % taskref     "taskref">
<!ENTITY % exampleref  "exampleref">
<!ENTITY % summaryref  "summaryref">

The definition module goes on to define the elements. The definition for the howto element restricts the content list for the collection to the metadata for the topic, references to any number of concept topics, references to task topics and optional example topics, and a topic acting in the role of a concluding summary. In addition, the howto element refers to the topic that provides an overview of the contents.

<!ELEMENT howto ((%topicmeta;)?, (%conceptref;)*, ((%taskref;), (%exampleref;)?)+,
      (%summaryref;))>
<!ATTLIST howto
  navtitle     CDATA     #IMPLIED
  id           ID        #IMPLIED
  href         CDATA     #IMPLIED
  keyref       CDATA     #IMPLIED
  query        CDATA     #IMPLIED
  conref       CDATA     #IMPLIED
  copy-to      CDATA     #IMPLIED
  %topicref-atts;
  %select-atts;>

The conceptref and taskref elements have a restricted type, meaning that validating processing is obligated to report an error if the referenced topic doesn't have the declared type (or a specialization from the declared type):

<!ELEMENT conceptref ((%topicmeta;)?, (%conceptref;)*)>
<!ATTLIST conceptref
  href         CDATA     #IMPLIED
  type         CDATA     "concept"
  ...>
<!ELEMENT taskref    ((%topicmeta;)?, (%taskref;)*)>
<!ATTLIST taskref
  href         CDATA     #IMPLIED
  type         CDATA     "task"
  ...>

The exampleref and summaryref elements don't restrict the type but, instead, assign roles to the referenced topics. Because the content list of the howto collection topic allows a topic to act as an example and requires a topic to act as a summary, the author is prompted to create topics in those roles, and the roles can be used in processing, for instance, to add a lead-in word to the emitted topic titles.

<!ELEMENT exampleref  ((%topicmeta;)?, (%exampleref;)*)>
<!ATTLIST exampleref
  ...>
<!ELEMENT summaryref  ((%topicmeta;)?)>
<!ATTLIST summaryref
  ...>

On closer investigation, either or both of these particular roles may turn out to reflect a persistent topic structure or semantic, in which case it would be appropriate to define topic types and limit the corresponding topicref specialization to topics of those types. The general technique, however, of assigning a role to a topic in the context of a collection remains valid.

Finally, the definition module sets the class attribute to declare that the new elements derive from topicref and are provided by the howto package:

<!ATTLIST howto %global-atts;
    class CDATA "- map/topicref howto/howto ">
<!ATTLIST conceptref %global-atts;
    class CDATA "- map/topicref howto/conceptref ">
...

Assembling the shell DTD

As with topic domains, a shell DTD assembles the base map module with the entities file and definition module for the how-to domain:

<!--vocabulary declarations-->
<!ENTITY % howto-d-dec PUBLIC "-//IBM//ENTITIES DITA How To Map Domain//EN" "howto.ent">
  %howto-d-dec;
...

<!--vocabulary substitution (one for each extended base element,
    with the names of the domains in which the extension was declared)-->
<!ENTITY % topicref  "topicref | %mapgroup-d-topicref; | %howto-d-topicref;">

<!--vocabulary attributes (must be declared ahead of the default definition) -->
<!ENTITY included-domains "&mapgroup-d-att; &howto-d-att;">

<!--Embed map to get generic elements -->
<!ENTITY % map-type PUBLIC "-//IBM//Elements DITA Map//EN" "../../dtd/map.mod">
  %map-type;

<!--vocabulary definitions-->
...

<!ENTITY % howto-d-def PUBLIC "-//IBM//ELEMENTS DITA How To Map Domain//EN" "howto.mod">
  %howto-d-def;

Creating a collection with the domain

Using the shell DTD, a map could include one or more how-to collections, as in the following example:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//IBM//DTD DITA How To Map//EN"
  "howtomap.dtd">
<map>
  <!-- how-to clusters can appear anywhere in a map hierarchy but always
       follow a consistent information pattern within the how to -->
  <howto href="dita-mapdomains.xml">
    <conceptref href="informationArchitecture.xml"/>
    <conceptref href="mapBackground.xml"/>
    <conceptref href="formalCollection.xml"/>
    <conceptref href="mapSpecialization.xml"/>
    <taskref href="implementDomain.xml"/>
    <exampleref href="declareEntities.xml"/>
    <exampleref href="domainModule.xml"/>
    <exampleref href="assembleDTD.xml"/>
    <exampleref href="domainInstance.xml"/>
    <summaryref href="summary.xml"/>
  </howto>
</map>

In fact, this example is the map for the article that you're reading right now. That is, as you may well have noticed, this article conforms to the formal pattern for a how-to collection. Here's the list of topics in this how-to article but with the addition of the topic type or role and title:

howto: How to define a formal information architecture with DITA map domains
- concept: Formal information architecture
- concept: Specializing topics and maps
- concept: The how-to collection
- concept: Map specialization
- task: Implementing a map domain
- example: Declaring the map domain entities
- example: Defining the map domain module
- example: Assembling the shell DTD
- example: Creating a collection with the domain (this topic)
- summary: Summary

While this article contains only a how-to collection, a how-to collection could be part of a larger deliverable. For instance, a help system could include multiple how-tos as part of a navigation hierarchy. Similarly, how-to collections could be used in books by creating a new shell DTD that combines the bookmap map type with the how-to map domain.

As you explore collection types, you'll find that, in addition to topics, a collection can aggregate smaller collections. For instance, you could create domains for a how-to collection, a case study collection, and a reference set collection. A product information collection could then require a product summary topic and at least one of each of these subordinate collections in that order.

You'll also find that, to represent a high-level relationship with a collection, you can create a relationship to the root topic for the collection branch. As the introduction and entry point for the collection, the root topic should provide the most statement of the content of the collection. That is, you can treat the set of topics as a collective content object, using the root topic to represent the collection as a whole for navigation and cross references.

Summary

In this article, you've learned how to specialize the topicref element to mandate a specific collection of topics. For complete, single-purpose collections such as functional specifications and quick reference guides, you might package these specialized topicref elements with a new map type. For building-block collections (such as how-tos or case studies) that can appear within a large deliverable, especially when different designers might create different collection types, you might want to package the specialized topicref elements as a map domain.

By specializing a DITA map in this way, you can implement a formal information architecture not just at the micro level within topics but at the macro level across topics. By defining such large-scale collective content objects, you can provide guidance to authors and declare semantics for processors with the end result that users have consistent and complete information deliverables.

DITA Open Toolkit, version 1.8.M2