Representing Software System Information in a Topic Map: A markup-centered approach

Terrence Brady
terry.brady@lexisnexis.com

Abstract

This presentation will show how a company that uses XML on a large scale to deliver content to customers used XML technologies to make the management of software development easier.

I led an effort to create an IS map for a complex set of interdependent metadata applications that had been developed over a period of 10–15 years. Having worked with these applications for years, I had a good sense of how the systems related to each other. My challenge was to build a presentation to explain and sell a system evolution plan. I reviewed documents that we had created over the years; while I found many excellent documents, I did not find a single document that I wanted to use as a basis for this effort.

The presentation will demonstrate how we achieved some success with traditional data modeling tools that were available to us. We created a DTD model to describe a collections of software built over 10–15 years.

The presentation will demonstrate how we achieved the most satisfying results using XML Topic Maps.

Using a fictitious (and simplified) Editorial System example, I will demonstrate the creation of a pictorial model, a DTD model and finally a Topic Map model— comparing and contrasting the models along the way.

Keywords: DTD; Topic Maps; Modeling

Terrence Brady

BS in Science with Computer Science minor from the University of Notre Dame, 1990

As a Consulting Software Engineer with LexisNexis0, I have developed numerous data conversion, metadata, and editorial system applications since 1990. I have served as a technical lead on several XML-related development projects since 2000.

Representing Software System Information in a Topic Map

A markup-centered approach

Terrence Brady [LexisNexis]

Extreme Markup Languages 2004® (Montréal, Québec)

Copyright © 2004 Terrence Brady. Reproduced with permission.

Purpose of this presentation

This presentation will show how a company that uses XML on a large scale to deliver content to customers used XML technologies to make the management of software development easier.

I led an effort to create an IS map for a complex set of interdependent metadata applications that had been developed over a period of 10–15 years. Having worked with these applications for years, I had a good sense of how the systems related to each other. My challenge was to build a presentation to explain and sell a system evolution plan. I reviewed documents that we had created over the years; while I found many excellent documents, I did not find a single document that I wanted to use as a basis for this effort.

In this exercise, I will explain the process that my team followed using a fictitious (and simplified) editorial system. I will include additional information about my team's actual experiences throughout the presentation.

Scenario: Modeling a legacy editorial system in preparation

Suppose that you need to model a complex editorial system in preparation for a project that will significantly evolve the legacy system. Documentation may exist in a variety of forms, but you need a single mechanism to convey the components of the system to the development team. What approach might you take? The three principal options are as follows:

  1. Draw a picture
  2. Write a “document”
  3. Utilize modeling technologies

What capabilities are needed from this documentation?

In order to describe a complex software system, the tools to be chosen must meet specific criteria.

  • Data collection must be fast. A terse format is needed to expedite not only the creation of the data, but also for the review and maintenance of the data.
  • Good expressive capabilities are needed to make the information easy to understand. A document that requires the author to present and explain the information each time that it is read is likely to have a limited life. The documentation must be available when the reader wants it.
  • Good navigation capabilities are essential to allowing a variety of users to discover the information that they need.

Draw a Picture of the System

Pictures are a familiar way to convey information. Consider a big-picture overview of a fictitious editorial system that we wish to model:

Figure 1: Editorial Workflow: System Applications
[Link to open this graphic in a separate page]

Note in this example that the Publication System reads data from the Document Management System, the Pricing System and the Royalty System. The Publication System updates the Media Composition System. The Workflow System manages the invocation of the Publication System.

Next, consider the addition of information about the hardware platform on which each application runs. Colors are utilized to distinguish hardware platforms. Information has been added about the users that interface with the system.

Figure 2: System Applications with Platform and Users
[Link to open this graphic in a separate page]

This example demonstrates that the Publication System is used by Marketing and Editorial Production users. The Rule Engine Server is a background application that the Publication System queries. The Publication System is a windows-based application.

Reviewing the modified overview, we find that it is not quite accurate to indicate that the Publication System reads the Pricing System. In reality, the data exchange is occurring through the Pub Control Database. In the following example, data stores have been added to the diagram. While adding the data stores, you remember that these data stores are also queried by an enterprise Report Tool. The following diagram might result:

Figure 3: System Components and Data Stores
[Link to open this graphic in a separate page]

Note in this example that the Publication System reads from the Pub Control Database. Several other applications read from and write to the Pub Control Database.

This picture is starting to get busy. Note the increase in complexity by expanding the scope of this document to include the enterprise Report Tool. The thought of increasing the scope of this diagram further is somewhat daunting. Our documentation has now filled an entire page. Any additions to the picture are going to require breaking the picture out to multiple pages.

The lesson learned from this exercise is that picture-based documentation can only go so far. It is not a great way to capture information. Our team experienced this as well. We had created an elaborate single-page IS map several years ago. The diagram was carefully constructed to eliminate overlapping arrows. As a result of its complexity, a magnifying glass was almost needed to read the text on the chart. More importantly, no one ever modified that diagram again.

The value of a picture is in its presentation capabilities. Pictures are difficult to maintain – especially beyond one page. Also, a picture tends to emphasize one aspect of a problem well at a given time (data flow vs. system flow).

Write a Document describing your System

Another familiar approach is to use a desktop authoring application (word processor, spreadsheet).

A word processor document is an ideal way to convey information on a specific subject, but as the number of items being described increases, the linear form of a word processor document is difficult for information discovery.

A spreadsheet can facilitate the discovery of certain pieces of information; but a spreadsheet cannot express an indefinite number of relationships. A simplified “spreadsheet” example follows

Table 1
Application Relationship Platform
Document Management   Unix
Document Editing updates Document Management Windows
Quality Check updates Document Management Windows
Publication reads Document Management, Pricing, Royalties Windows
Media Composition reads Publication Unix
Pricing   MVS
Royalty   MVS

Utilize Modeling Technologies

Formal modeling techniques provide tools that support multiple dimensions of complexity.

UML [Unified Modeling Language]

UML is the technology designed for documenting complex systems; however, UML can be cumbersome when one tries to collect a large amount of information on a legacy system. Also, UML is not intuitive for end-users. Vendor inter-operability issues may also exist.

My team discussed using UML several times. While we found some aspects of UML — such as use cases — to be very helpful, we never wanted to invest in documenting our legacy applications in UML. What we wanted was a “lite” version of UML using technology that we already had available to us.

Data Modeling

DTD [Document Type Definition] modeling can provide some powerful capabilities for describing a system.

My team was in the process of developing a DTD to describe a new metadata output store. As we played with the data model in a modeling tool, we saw that there was strong potential for our “IS” map. The simple DTD operators (+, *, ?) and the notion of element containment are convenient ways to express the containment of software components within an application or to express the schema of a data store.

The ability to define an element and its contents without immediately knowing all of the uses of that element permits engineers to grow the system model over a period of time.

Similar to the data modeling exercise that my team followed, consider creating a DTD to represent the applications described in the pictures above “Editorial Workflow: System Applications”. The following code models the system interaction for the sample Editorial System:

<?xml version='1.0' encoding='UTF-8' ?>

<!--Generated by Turbo XML 2.3.1.100.-->

<!ELEMENT sys:DocManagementSystem EMPTY>

<!ATTLIST sys:DocManagementSystem  unix CDATA  #IMPLIED >
<!ELEMENT sys:QualityCheckSystem (role:readWrite , sys:DocManagementSystem)>

<!ATTLIST sys:QualityCheckSystem  windows CDATA  #IMPLIED >
<!ELEMENT role:readWrite EMPTY>

<!ELEMENT sys:DocumentEditingSystem (role:readWrite , sys:DocManagementSystem)>

<!ATTLIST sys:DocumentEditingSystem  windows CDATA  #IMPLIED >
<!ELEMENT sys:PublicationSystem (role:read , sys:DocManagementSystem , 
sys:PricingSystem , sys:RoyaltySystem)>

<!ATTLIST sys:PublicationSystem  windows CDATA  #IMPLIED >
<!ELEMENT role:read EMPTY>

<!ELEMENT sys:PricingSystem EMPTY>

<!ATTLIST sys:PricingSystem  mvs CDATA  #IMPLIED >
<!ELEMENT sys:RoyaltySystem EMPTY>

<!ATTLIST sys:RoyaltySystem  mvs CDATA  #IMPLIED >
<!ELEMENT sys:MediaCompositionSystem (role:read , sys:PublicationSystem)>

<!ATTLIST sys:MediaCompositionSystem  unix CDATA  #IMPLIED >
<!ELEMENT sys:WorkflowSystem (role:invokes , sys:DocManagementSystem , 
sys:DocumentEditingSystem , sys:PublicationSystem , sys:MediaCompositionSystem)>

<!ATTLIST sys:WorkflowSystem  windows CDATA  #IMPLIED
                                unix    CDATA  #IMPLIED >
<!ELEMENT role:invokes EMPTY>
Note the brevity of this model. It can be printed on a single page and reviewed and validated quickly by a team of engineers. The Publication System element (sys:PublicationSystem) contains a read relationship to other systems.

In this example, namespaces can provide a typing mechanism. The “sys” namespace is reservered for system components; attributes are used for properties.

One awkward aspect of this DTD is the difficulty of explaining the different ways each application relates to the others. The “role” namespace on a preceding sibling element is used to distinguish a read relationship from an update or invoke relationship.

The modular nature of DTD's provided useful ways to extend the model. As we did to the initial pictorial representation “System Applications with Platform and Users”, user information has been added to the model. The modular nature of DTD's would allow this information to be created in a separate DTD module that would import the first module.

<!ELEMENT role:uses EMPTY>

<!ELEMENT user:Marketing (role:uses , sys:PublicationSystem , 
sys:MediaCompositionSystem)>

<!ELEMENT user:EditorialProduction (role:uses , sys:PublicationSystem , 
sys:MediaCompositionSystem)>

<!ELEMENT user:QA (role:uses , sys:QualityCheckSystem , sys:MediaCompositionSystem)>

<!ELEMENT user:BusinessAnalyst (role:uses , sys:PricingSystem , sys:RoyaltySystem)>
Note in this example that the user:EditorialProduction element and the user:Marketing element each contain the sys:PublicationSystem element.

Data stores could be added in a similar fashion to another DTD module. My team found that commercial DTD editing and viewing tools provide good discovery and design capabilities. The following example visually shows the Publication System is invoked by the Workflow System and that the Publication System reads from the Document Management System, the Pricing System and the Royalty System.

Figure 4: System Overview in a DTD visualization tool
[Link to open this graphic in a separate page]

Using DTD rendering tools you can provide bidirectional navigation through the model as well as a printer-friendly rendering of the entire model. Note that hypertext links are available from the parent to the child elements of the Publication System: Pricing System, DocManagement System and Royalty System. Hypertext links are also available to the users and systems that contain the Publishing System.

Figure 5: System Overview DTD as a web page
[Link to open this graphic in a separate page]

The concepts that we were trying to model were immediately clear to a wider audience of engineers with one exception: the use of a role as a predecessor element was awkward to explain. The predecessor role element had to be explained. We were able to create a comprehensive model of years of development in a few days. The review of the model was efficient: we made the web pages available prior to the meeting, and we stepped line by line through the DTD focusing on each line of the DTD as a distinct assertion.

We presented the same model to our internal audience. They expressed enthusiasm about the information that we wanted to make available to them; the were excited by the navigability of the model. We found that the audience was not satisfied with the model on its own. They needed the information to be presented to them. The expressive capabilities of the DTD were difficult for them to understand. The data was excellent, but the lack of accessible annotations was frustrating. We added comments to the DTD, but the model could not stand on its own.

One primary obstacle remained: How to distinguish the interaction between 2 applications from the interaction between a user and an application. A DTD can only indicate that element “A” contains element “B” exactly once, one or more times, zero or one times or zero to many times. A DTD cannot describe the containment. An additional layer of elements could be added to express containment, but the tags would be quite awkward: sys:PublicationSystem contains sys:PublicationSysterm-Reads which contains sys:PricingSystem, sys:RoyaltySystem, sys:DocManagmentSystem.

A DTD model has potential within the engineering team. It did not satisfy the needs of our audience.

Topic Map Modeling

My team had seen a few presentations on XML Topic Maps and was curious to see how the expressive capabilities of a Topic Map would work with our model.

One member of my team volunteered to translate our DTD model into XTM [XML Topic Map ] by hand. Presented with an XTM version of the same model, our audience was satisfied with the results. The data was accessible and understandable. The topic map rendering of the data model solved the expressive limitations of our previous DTD data model by being able to annotate the language of each association between objects.

One challenge remained: the generation of the XTM by hand was not a sustainable solution for us. At the same time, we were not yet ready to constrain our vocabulary into a DTD that could be converted to XTM, nor did we have enough of a commitment to purchase and use a topic map editor.

We were pleased to discover Ontopia's proposed LTM [Linear Topic Map ] format due to its brevity and readability.

While this presentation will not attempt to explain the concept of Topic Maps, I will provide a very quick summary of the LTM Syntax.

  • Topics are the objects to be discussed in the topic map. They are defined within brackets “[]” and classified with a colon operator “:”.
    • [day:city = “Dayton, OH”]
      This defines a topic “day” with the name “Dayton, OH”. This topic is a subtopic of the topic “city”.
    • [oh:state = “Ohio”]
      This defines a topic “oh” with the name “Ohio”. This topic is a subtopic of the topic “state”.
  • Associations between topics are expressed with an association name followed by a parenthetical group containing the association participants.
    • within(day, oh)
      The “within()” expression conveys an association between the topic “day” and the topic “oh”. The term “within” itself is a topic which should be defined as well.
    • [within = “is a city within the following state” / city
      = “contains the following cities” / state]
      The definition above defines a topic “within”. Its name varies for each participant that participates within the association. The slash is used to convey a role within an association. When a city participates in the association (see “/ city”) the association will be named “is a city within the following state”.
  • Occurrences of specific topic resources are captured within curly braces {}. The values within the braces are topic, type and resource information. Links are provided to resource data either within or external to the topic map.
    • {day, homepage, http://www.cityofdayton.org/}
      The topic “day” has an occurrence of a “homepage” which can be found at the specified URL. “homepage” itself is a topic which can be defined.
    • {day, nickname, [[Gem City]]}
      The topic “day” has an occurrence of a “nickname” which is defined within the double brackets. “nickname” itself is a topic which can be defined.

The following code shows our editorial system model as captured in LTM syntax. This model captures the Applications defined in our first diagaram. At the top of the example, note the definition of each Application Topic. The code contains the definition of association terms (read, update, invoke). The language of each association is defined by topic type in the definition (see the “/” operator). Note the creation of the actual associations at the bottom of the example.“Editorial Workflow: System Applications”

[app          = "Application"]
[appDm:app    = "Application: Document Management System"]
[appDe:app    = "Application: Document Editing System"]
[appPub:app   = "Application: Publication System"]
[appComp:app  = "Application: Media Composition System"]
[appQC:app    = "Application: Quality Check System"]
[appPrice:app = "Application: Pricing System"]
[appRoyal:app = "Application: Royalty System"]
[appWf:app    = "Application: Workflow System"]

[target = "Target"]
[update = "Updates" 
  = "updates" /app
  = "is updated by" / target]
[read = "Reads" 
  = "reads" /app
  = "is read by" / target]
[invoke = "Invokes" 
  = "invokes" /app
  = "is invoked by" / target]

update(appDe, appDm:target)
update(appQC, appDm:target)
read(appPub, appDm:target)
read(appComp, appPub:target)
read(appPub, appPrice:target)
read(appPub, appRoyal:target)
invoke(appWf, appDm:target)
invoke(appWf, appDe:target)
invoke(appWf, appPub:target)
invoke(appWf, appComp:target)

In the following example, hardware platform information is assigned via occurrences. User Topics are defined and then associated to the appropriate applications.“System Applications with Platform and Users”

[appRules:app = "Application: Rules Engine Server"]
read(appPub, appRules:target)

[platform         = "Hardware Platform"]
[unix:platform    = "Unix"]
[windows:platform = "Windows"]
[mvs:platform     = "MVS"]
{appDm,      unix,     [[prod101]]}
{appDe,      windows,  [[desktop app]]}
{appPub,     windows,  [[desktop app]]}
{appComp,    unix,     [[prod102]]}
{appQC,      windows,  [[cert104]]}
{appPrice,   mvs,      [[SYSPROD]]}
{appRoyal,   mvs,      [[SYSPROD]]}
{appRules,   unix,     [[prod101]]}[user = "User"]
[uAuthor:user = "User:Author"]
[uMkt:user    = "User: Marketing"]
[uProd:user   = "User: Editorial Production"]
[uQA:user     = "User:Quality Assurance"]
[uBus:user    = "User: Business Analyst"]

[uses = "Uses" 
  = "uses" /user
  = "is used by" / app]
uses(uAuthor, appDm)
uses(uAuthor, appDe)
uses(uMkt, appPub)
uses(uMkt, appComp)
uses(uProd, appPub)
uses(uProd, appComp)
uses(uProd, appRoyal)
uses(uQA, appQC)
uses(uQA, appComp)
uses(uBus, appPrice)
uses(uBus, appRoyal)

In the next example, data stores are added and related to their corresponding applications. The model is extended to contain the enterprise Report Tool.“System Components and Data Stores”

[data         = "Data Store"]
[dPrint:data  = "Data: Print Product"]
[dCD:data     = "Data: CD Product"]
[dWeb:data    = "Data: Web Product"]
[dPubCnt:data = "Data: Publication Control Database"]
[dFin:data    = "Data: Financial Database"]


[updateData = "Update Data Store" 
  = "updates the following data" /app
  = "is updated by the following applications" / data]
[createData = "Create Data Store" 
  = "creates the following data" /app
  = "is created by the following applications" / data]
  
createData(appComp, dPrint)
createData(appComp, dCD)
createData(appComp, dWeb)
updateData(appRoyal, dFin)
updateData(appRoyal, dPubCnt)
updateData(appPrice, dFin)
updateData(appPrice, dPubCnt)
updateData(appQC, dPubCnt)
updateData(appComp, dPubCnt)
updateData(appPub, dPubCnt)[appRptSrv:app = "Application: Report Server"]
[appRpt:app    = "Application: Report Tool"]
read(appRpt, appRptSrv:target)

[readData = "Read Data Store" 
  = "reads the following data" /app
  = "is read by the following applications" / data]
readData(appRptSrv, dFin)
readData(appRptSrv, dPubCnt)
uses(uAuthor, appRpt)
uses(uMkt, appRpt)
uses(uQA, appRpt)
uses(uProd, appRpt)
uses(uBus, appRpt)

The LTM file has comparable brevity to that of the DTD along with much greater expressive capabilities.

Viewing the data within a topic engine reveals the information discovery capabilities of a Topic Map. Each relationship is not only available as a link, but it is annotated. Note: In the live presentation, a demonstration will be done at this point. The following pictures are contained for the online audience.

Figure 6: Publication System Application as viewed through a Topic Map engine
[Link to open this graphic in a separate page]

Note that the Topic Map engine has provided all of the information that is known about the Publication System. The relationship to the Workflow System is described as “is invoked by”. The relationship to the Document Management System is described as “reads”. The Topic Map indicates that the Publication System “updates” the Publication Control Database. The Occurrence data indicates that this is a windows desktop application.

Every item shown by the Topic Map server is a hypertext link to related items. If you follow the link to the Publication Control Database, the following page will display:

Figure 7: Publication Control Database Data Store as viewed through a Topic Map engine
[Link to open this graphic in a separate page]

Note that a similar interface is used for the Publication Control Database Data Store. The language of the relationship to the Publication System is altered. The relationship indicates that the Publication Control Data “is updated by” the Publication System.

With the Topic Map rendering of our model, our audience was able to find answers to their questions independently, without assistance from engineers. Also, the network of links allowed the engineering team to discover some associations that we had not considered before.

SVG [Scalable Vector Graphics] Rendering of the Topic Map — taking it to the next level

A topic map can be exported as XML and further transformed into additional formats. The next example will show a rudimentary graphical representation of the same system information generated from the topic map XML.

Figure 8: SVG Rendering of application interactions from exported XTM file
[Link to open this graphic in a separate page]

This figure is displaying a graphical view of a portion of the topic map file. Note in this example that the Publication System is read by the Media Composition System (inbound red arrow) and the Publication System reads from 4 other systems (outbound red arrow). The yellow arrow indicates that the Workflow System launches the Publication System.

While this diagram is fairly simplistic, it does illustrate the possibility of generating pictorial views from the topic map source files.

The following stylesheet was used to generate the SVG diagram displayed above.

This code initializes the stylesheet, several variables and defines SVG code to draw arrow heads at the end of a line.

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:tm="http://www.topicmaps.org/xtm/1.0/"
                xmlns:xlink="http://www.w3.org/1999/xlink" 
                xmlns="http://www.w3.org/2000/svg">

<!--This stylesheet will produce an SVG rendering of the application interactions 
from the example topic map exported as XTM-->
<xsl:output omit-xml-declaration="no" method="xml" 
  doctype-public="-//W3C//DTD SVG 1.0//EN" 
  doctype-system="http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" 
  indent="yes" /> 

<!--Variables to control the overall shape of the generated picture-->
<xsl:variable name="boxHeight">36</xsl:variable>
<xsl:variable name="boxWidth">250</xsl:variable>
<xsl:variable name="indent">300</xsl:variable>
<xsl:variable name="vgap">4</xsl:variable>
<xsl:variable name="textVoff">18</xsl:variable>
<xsl:variable name="textHoff">5</xsl:variable>

<!--Process the root node-->
<xsl:template match="/">
<svg 
  xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
  xml:space="preserve">
  <defs> 
    <!--See http://www.w3.org/TR/SVG/painting.html#Markers for arrow points-->
    <marker id="redTriangle" viewBox="0 0 10 10" refX="0" refY="5" 
      markerUnits="strokeWidth" markerWidth="4" markerHeight="3" 
      orient="auto" style="fill:red;stroke:red"> 
      <path d="M 0 0 L 10 5 L 0 10 z"/> 
    </marker> 
    <marker id="greenTriangle" viewBox="0 0 10 10" refX="0" refY="5" 
      markerUnits="strokeWidth" markerWidth="4" markerHeight="3" 
      orient="auto" style="fill:green;stroke:green"> 
      <path d="M 0 0 L 10 5 L 0 10 z"/> 
    </marker> 
    <marker id="yellowTriangle" viewBox="0 0 10 10" refX="0" refY="5" 
      markerUnits="strokeWidth" markerWidth="4" markerHeight="3" 
      orient="auto" style="fill:yellow;stroke:yellow"> 
      <path d="M 0 0 L 10 5 L 0 10 z"/> 
    </marker> 
  </defs> 
  <g id="mainlayer">
    

This code first finds all applications within the topic map and invokes a template to draw each application as a box. Then, each application to application association is located and a method is called to represent the association as a curved arrow. Each association type has been assigned a unique color.

<!--Find all topics of type application-->
    <xsl:apply-templates select=
    "tm:topicMap/tm:topic[tm:instanceOf/tm:topicRef/@xlink:href='#app']"/>         

    <!--Find all associations between 2 applications, color code each type-->
    <xsl:apply-templates select=
    "tm:topicMap/tm:association[tm:instanceOf/tm:topicRef/@xlink:href='#invoke']">
      <xsl:with-param name="color">yellow</xsl:with-param>
    </xsl:apply-templates>
    <xsl:apply-templates select=
    "tm:topicMap/tm:association[tm:instanceOf/tm:topicRef/@xlink:href='#read']">         
      <xsl:with-param name="color">red</xsl:with-param>
    </xsl:apply-templates>
    <xsl:apply-templates select=
    "tm:topicMap/tm:association[tm:instanceOf/tm:topicRef/@xlink:href='#update']">         
      <xsl:with-param name="color">green</xsl:with-param>
    </xsl:apply-templates>
  </g>

</svg>
</xsl:template>

This template creates a box for a given application.

<!--Create a box for each application-->
<xsl:template match="tm:topic">
  <xsl:variable name="pos">
    <xsl:value-of select="position()*($boxHeight+$vgap)"/>
  </xsl:variable>
  <rect style="fill:linen;stroke:black">
    <xsl:attribute name="x"><xsl:value-of select="$indent"/></xsl:attribute>
    <xsl:attribute name="y"><xsl:value-of select="$pos"/></xsl:attribute>
    <xsl:attribute name="width">
      <xsl:value-of select="$boxWidth"/>
    </xsl:attribute>
    <xsl:attribute name="height">
      <xsl:value-of select="$boxHeight"/>
    </xsl:attribute>
  </rect>
  <text>
    <xsl:attribute name="x"><xsl:value-of select="$indent"/></xsl:attribute>
    <xsl:attribute name="dy"><xsl:value-of select="$textVoff"/></xsl:attribute>
    <xsl:attribute name="dx"><xsl:value-of select="$textHoff"/></xsl:attribute>
    <xsl:attribute name="y">
      <xsl:value-of select="$pos"/>
    </xsl:attribute>
    <xsl:apply-templates select="tm:baseName/tm:baseNameString"/>
  </text>
</xsl:template>

This template draws a curved line from one application box to another application box. Offsets are applied to each line to reduce line overlap.

<!--Represent each association with a curved arrow-->
<xsl:template match="tm:association">
  <xsl:param name="color">green</xsl:param>
  <xsl:variable name="relindent">
    <xsl:value-of select="(position()) div (last())"/>
  </xsl:variable>
  <xsl:comment>
    <xsl:value-of select="concat(position(),',',last(),',',$relindent)"/>
  </xsl:comment>

  <!--The index of the app within the list of applications will determine curve 
  coordinates-->
  <xsl:variable name="sourceref" select="substring(
  tm:member[tm:roleSpec/tm:topicRef/@xlink:href='#app']/tm:topicRef/@xlink:href,
  2)"/>
  <xsl:variable name="source">
    <xsl:for-each select=
    "/tm:topicMap/tm:topic[tm:instanceOf/tm:topicRef/@xlink:href='#app']">
      <xsl:if test="@id=$sourceref">
        <xsl:value-of select="position()"/>
      </xsl:if>
    </xsl:for-each>
  </xsl:variable>
  
  <xsl:variable name="targetref" select="substring(
  tm:member[tm:roleSpec/tm:topicRef/@xlink:href='#target']/tm:topicRef/@xlink:href,
  2)"/>
  <xsl:variable name="target">
    <xsl:for-each select=
    "/tm:topicMap/tm:topic[tm:instanceOf/tm:topicRef/@xlink:href='#app']">
      <xsl:if test="@id=$targetref">
        <xsl:value-of select="position()"/>
      </xsl:if>
    </xsl:for-each>
  </xsl:variable>
  
  <path>
    <xsl:attribute name="style">
      <xsl:text>fill:none</xsl:text>
      <xsl:text>;stroke:</xsl:text>
      <xsl:value-of select="$color"/>
      <xsl:text>;stroke-width:3;marker-end:url(#</xsl:text>
      <xsl:value-of select="$color"/>
      <xsl:text>Triangle)</xsl:text>
    </xsl:attribute>
    <xsl:attribute name="d">
      <xsl:text>M</xsl:text>
      <xsl:value-of select="$indent"/>
      <xsl:text>,</xsl:text>
      <xsl:value-of select=
      "($source )*($boxHeight+$vgap)+($relindent*$boxHeight*.8)"/>
      <xsl:text> Q</xsl:text>
      <xsl:value-of select="$indent*$relindent*.6"/>
      <xsl:text>,</xsl:text>
      <xsl:value-of select="($source+$target)*$relindent*($boxHeight+$vgap)"/>
      <xsl:text> </xsl:text>
      <xsl:value-of select="$indent"/>
      <xsl:text>,</xsl:text>
      <xsl:value-of select=
      "($target )*($boxHeight+$vgap)+($relindent*$boxHeight*.8)"/>
    </xsl:attribute>
  </path>
</xsl:template>

</xsl:stylesheet>

A more complicated stylesheet would be needed to create a truly usable diagram. Once written, such a stylesheet could be generated to allow a user to visualize a variety of aspects of a large system.

Conclusion

My team started its documentation effort using traditional approaches. We found the legacy desktop application documents too limiting to convey the breadth of the information that we wanted to manage. We found pictorial representations to be unwieldy; our biases said that we would encounter the same problem with UML.

As an experiment, we played with our existing data modeling tools and made significant progress. We gained a new appreciation for DTD syntax in the process. I had always considered DTD's to be archaic, but I gained an appreciation of their brevity as an assertion language.

We found a Topic Map rendering of our model to be superior to all of the other options that we explored, and our audience agreed. They could navigate to their own answers, which pleased both them and us

The LTM syntax provided us with a viable method for building up Topic Map resources. Hopefully, we will sell this approach to a larger group.

Although, the original project that initiated our modeling effort is currently on hold, the model itself is gaining interest within our organization. My team has already benefitted from the process that we followed. On a project that started this year, we used a Topic Map model to define the impacts of a major project on a subset of our systems. We mapped project requirements to system components, issues and business rules.

XML Topic Maps could provide a tremendous bridge in explaining an inventory of software components to a non technical audience.


Acknowledgments

Thanks to Brian Vacha for introducing me to Topic Map and SVG technologies.

Thanks to Bob DuCharme and Eric Freese for guidance on how to focus the presentation.

Thanks to Graham Segroves for editorial input in the document.


Bibliography

[Omnigator] Topic Map visualizations shown with Ontopia's Omnigator topic map engine.

[TurboXML] DTD visualizations shown with Tibco's TurboXML and SchemaDoc tools.



Representing Software System Information in a Topic Map

Terrence Brady [LexisNexis]
terry.brady@lexisnexis.com