One of the elements that is unique to the linklist structure is also one of the least understood: the linkinfo element. The DITA 1.2 Spec itself merely says that it lets you “place a descriptive paragraph after the links that are contained in a linklist element.” But a linklist already allows the title and desc elements to provide description, so how does this element add anything more to the design? Naturally, there is something more to this story, something we can trace from the foundations of human culture, as it were. 

Did you know?

In many of the expressions of human design (for example in art, architecture, products, and even forms of literature) we tend to admire and appreciate instances of design that follow predictable and time-tested formats. Greek architects developed the architectural orders of Doric and Ionic design that persist into building designs even today. Writers developed the classic structures still used for storytelling, persuasion, news reporting, and encyclopedic entries. The user experience engineers and designers of our cars, clothing, and consumer electronics make use of branding and layout conventions that help consumers interact easily with those goods.

Across all these endeavors, design principles have been codified as schemas or business rules that can be used both by students of these arts as well as — increasingly — computers to generate instances of these principles for our use.^{Footnote 1}

NCinDC / Foter / CC BY-ND

Architecture and writing in particular have enjoyed the collaborations of theorists on both sides in contributing to a legacy of concepts shared between the disciplines. As with the forms of architecture that get repeated across buildings of different types and uses, so our information systems also depend on many inferred forms of structure that are often repeated across literature of different types and roles.

These architectural forms in writing include titles, description, and discourse (the most common forms across nearly all uses of writing) as well as definition, explanation, dialog between actors (including humans and machines), alerts, references, comments, metadata, annotation, and more.

Among the principals of SGML and XML markup, architectural forms are used as a way to make assertions about the relationship of information between two or more different information types. If an independent rule is able to assert that the title of a blog post and the title of an essay are both instances of a primary title, a publishing or content management system can apply the same services to both instances, improving the efficiency of both search and publication.

And so the lowly linkinfo element in DITA’s related-links structure comes back on stage to receive a new distinction: as far as I can tell, it is one of the few elements in DITA^{Footnote 2} that go beyond description to formally support the architectural form role of “annotation,” or adding a gloss to an otherwise fully-described unit of content.

Deep Dive

• DITA 1.2 Spec: The linkinfo element
• Dr. Tony Self of Hyperwrite, in his eBook The DITA Style Guide, adds some considerations for the practical use of the linkinfo element.
• Structuring XML Documents, Part Four: DTD Design with Architectural Forms, by David Megginson (The Definitive XML Series From Charles F. Goldfarb)
• The Classical Orders of Architecture
• Wikipedia: Generative Design
• A note for DITA 2.0 consideration: should annotation be considered for other DITA structures? Consider the role of annotation as a feature of XML Schema markup, which allows annotation for each declaration.

________

^{Footnote 1}

Programmers often auto-generate test cases of every conceivable form of data used by their programs in order to make sure their algorithms handle these cases. Producers of boxed or canned goods often fall back on computer-generated layouts for more competitive shelf appeal. Entire housing neighborhoods may be initially designed by generative grammars that ensure code-compliant spacing between structures, use of land, ease of travel, closeness to schools and stores, and more. Artists and writers have their motifs, tropes, memes, rhetorical patterns, and emotional symbols. In a few cases where these conventions can be asserted as algorithms, computers can even generate passably readable news reports or abridged versions of human writing.

^{Footnote 2}

The other annotation-like elements in DITA are the notefn and fn (footnote) elements. Although draft-comment and required-cleanup also appear to be forms of annotation, I consider both to be examples of removing things out of the discourse, therefore they are more like the architectural form also found in programming: the comment.