advantages_of_using_DITA.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "task.dtd">
<task id="task_smw_dhg_23">
    <title>Assembling maps and topics</title>
    <shortdesc>DITA is useful for technical documents in general, and standards in particular.
        Standards can be assembled from topics in a disciplined manner.</shortdesc>
    <prolog>
        <author>John Gordon Tait</author>
        <copyright>
            <copyryear year="2012-2013"/>
            <copyrholder>John Gordon Tait</copyrholder>
        </copyright>
    </prolog>
    <taskbody>
        <section>
            <title>A topic-based approach allows information to belong in more than one
                place</title>
            <p>Organisations of all kinds can have vast number of documents to maintain. Many will
                need to be written and managed for regulatory or quality reasons. A structured
                approach can make a difference.</p>
            <p>Many documents will have significantly overlapping concepts. Efforts to write a
                policy or procedure the traditional ("bottom down") way can be thwarted by hard
                questions like “where does this information really belong?” This is a very difficult
                question to answer when information is contained in traditional documents.</p>
            <p>It’s a question that can go away when it is possible to reassemble a document from
                topics using a <i>map</i>, then assemble another document later using some of the
                same topics. The same information can live in more than one place, but can be
                managed as just one topic.</p>
            <p>In regulated industries, where it is essential that information is correct, this will
                allow you to manage overlapping content while being sure that there is no unwanted
                duplication or contradiction between different documentation sets.</p>
            <p>In standards, specific subject areas can fundamentally cut across disciplines. For
                example, engineering standards can be presented according to an asset owner, the
                asset lifecycle, from a systems view, or from the perspective of risk. None of these
                is definitively better than another.</p>
            <p>It would be a simple exercise to cut this kind of material up and reassemble it
                cleanly into manuals using DITA. The same information could be presented in more
                than one manual without the problem of deciding where it should best be placed.</p>
            <p>When you manage content like this (topics and maps), you don't need to know in
                advance how to best to arrange it, and you can change your mind. Or, if your team or
                organisation changes and has different priorities from before, you can create a new
                map without rewriting (much). Assembling maps for output and writing topics can be
                kept entirely separate.</p>
        </section>
        <section>
            <title>Writing topics</title>
            <p>Topics are written to be self-contained, within reason. They have useful, informative
                titles. A short summary, called the "short description", is often written under the
                title. Essential information, like tables or drawings, are kept in the topic where
                they are needed by the reader.</p>
            <p>Packets of information like this can then be far more easily assembled for
                publication. A topic can be used in different publications with the minimum (ideally
                no) rewriting.</p>
            <p>This approach was covered in great detail by an influential document <cite>STOP
                    (Sequential Thematic Organization of Publications)</cite>, by the Hughes
                Aircraft Company, from 1965. It's a genuine classic, witty and very readable. STOP
                calls the divided-down document a "river raft" document. Some of its ideas, like
                putting topics ("storyboards") on two facing pages, have dated only because
                technical standards can no longer be expected to be published only in print. Many of
                its other approaches are still highly useful. </p>
        </section>
        <section>
            <title>Cross-linking topics together with relationship tables</title>
            <p>DITA's maps allow topics to be listed and nested, like a table of contents. A map of
                topics for a publication will also contain a "relationship table". Cross-linking
                topics from one part of the publication to another is achieved by these relationship
                tables.</p>
            <p>Relationship tables are written inside maps, not topics. The relationship table
                explains how the topics link together, and allows cross-references to be produced.
                They show how a topic (in one column of a table) links to another (in the next
                column).</p>
            <p>Cross-references made directly from inside topic to other topic ("in-line links") are
                not usually used or are kept to a minimum.</p>
            <p>There are different ways to design relationship tables. What they all do is allow
                cross-references to be managed <i>without amending the topics</i>. Therefore, the
                author or the publications manager doesn't have to be concerned about managing
                complicated links. They can just list the required topics in the map in sequence,
                then add the links with the relationship table.</p>
            <p>If a new map for publication is designed and it uses some of the old topics and some
                new ones, no links will be broken because links will be added with a new
                relationship table.</p>
            <p>In published output, the cross-links are usually listed at the end of the topic. DITA
                topics are usually only a few hundred words long, so this is usually somewhat
                convenient for the reader.</p>
        </section>
    </taskbody>
</task>