Dynamic Navigation in DITA

hurriedtinkleAI and Robotics

Nov 15, 2013 (3 years and 1 month ago)

63 views

IBM User Technology

March 2004 | Dynamic Navigation in DITA

© 2004 IBM Corporation

Dynamic Navigation in DITA

Erik Hennum and Robert Anderson

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Agenda


The problem with static content

Challenges of integrating information components, serving multiple
audiences, and scaling to the enterprise


Solving the content problem with DITA

Creating content for many contexts

Specifying metadata properties such as the content audience


Solving the processing problem

Scoping and filtering content with an on
-
demand repository


Demo of solution



Getting started now

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

database server

web server

Problem 1: integrating components


Solutions integrate many different components


Different solutions use different subsets of the
functionality and information for the component


A site can install multiple solutions; all solutions
should share one instance of each component


The running solution needs the ability to show
only

its
subset of the content associated with the component

thin client framework


solution

portal

web application

query language

administration

department portal

solution

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

database

Problem 2: multiple audiences


The content has multiple audiences, each with a
different but overlapping set of concerns


One person can wear many hats and can have
different concerns at different times

programmer

administrator

query language

administration

schema development

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Problem 3: enterprise scale


Enterprise libraries offer too much content to navigate
with a global TOC and index; search is imprecise


User experience of infoglut


The problem can’t be solved with static aggregations of
content


components, audiences, and other categories
have too many permutations


?

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Topic

Solution: hide the content in the navigation


Hide an irrelevant topic by removing all navigation to the topic


Prune branches from the table of contents


Suppress links to the topic from other topics


Drop terms from the index


Skip hits in the search results


Dynamic navigation


Solve the content with DITA


Solve processing with Semantic Web technologies


Topic

Search

Index

Table of contents

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

DITA in a nutshell


DITA is a community XML architecture for reusable topics



Content strategy

Divide content in granular topics (about the size of a sensible HTML page)

Write each topic to stand on its own

Assemble deliverables by reusing topics in lots of different combinations



Design and processing strategy

Strong typing of topics to guide authors and precisely identify semantics

base types of concept, task, and reference

Specialize new information types from existing types to minimize design
and processing work


extend Reference with a API Reference type or
Task with a Tutorial type

Shared base types guarantee information interchange with other adopters

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

DITA topic example

<task id="installstorage">


<title>Installing hard drives</title>


<shortdesc>You open the box and insert the drive.</shortdesc>


<prolog><metadata>


<audience type="administrator"/>


<keywords>


<indexterm>hard drive</indexterm>


<indexterm>disk drive</indexterm>


</keywords>


<prodinfo>


<prodname>TeraDisk</prodname>


<vrmlist><vrm version="2" release="1"


modification="1"/></vrmlist>


</prodinfo>


</metadata></prolog>


<taskbody>


<prereq>First, purchase the hard drive. To avoid problems,


please leave the hard drive in the box for now.</prereq>


</taskbody>


<related
-
links>


<link href="unscrewcover.dita"/>


<link href="insertdrive.dita"/>


<link href="replacecover.dita"/>


</related
-
links>

</task>

Identifier and
title

Properties

Type
-
specific
content body

Relationships

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Content solution: context
-
free DITA topics


Markup encourages the author to write context
-
free content

Topics authored as self
-
contained coverage of one subject

Any topic can be a starting point with navigation to other topics


Topic qualified by properties

Metadata such as audience, product, platform, …

Processes can filter topics by querying for properties


Links to other topics specified outside the content

Processes can hide links because they aren’t embedded in content

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Content solution: context
-
specific maps


A DITA map organizes a set of topics in a hierarchy and sequence

Use to produce help systems, printable books, …

Different maps can organize the same topics in different ways

Can provide multiple views on the same topics: by product, by task, …


Setting properties of the topic at a position within the hierarchy

Properties include the title and metadata

Change the title relative to the parent topic

Metadata could identify the same topic as advanced in one deliverable
and basic in another


IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

DITA map example

<map title="Tasks">


<topichead navtitle="Installing"


audience="admin">


<topicmeta>


<shortdesc>Install products before


configuring or using them.</shortdesc>


<topicmeta>


<topicref href="installstorage.dita">


<topicref href="unscrewcover.dita"/>


<topicref href="insertdrive.dita"/>


<topicref href="replacecover.dita"/>


</topicref>


<topicref href="installwebserver.dita">


<topicref href="closeprograms.dita"/>


<topicref href="runsetup.dita"/>


<topicref href="restart.dita"/>


</topicref>


<topicref href="installdb.dita">


<topicref href="closeprograms.dita"/>


<topicref href="runsetup.dita"/>


<topicref href="restart.dita"/>


</topicref>


</topichead>




</map>

A heading doesn’t have to
have a topic

Title and properties can be
assigned in the map

A topic can appear multiple
times in the hierarchy

The map organizes a set of
topics in a hierarchy


IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Semantic Web technologies in a nutshell


Manages information about resources

Designed to support querying properties and traversing relationships

Designed to be scalable to the World Wide Web


Useful for navigation as well as semantic relationships

Useful for granular resources


Two alternative standards

RDF from w3c

TopicMaps from OASIS


Not a content management system

No version control, workflow, …

Can provide a deployable runtime repository that describes resources

Content management systems can also be runtime repository, especially
for enterprise websites

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Processing solution: repository
-
based delivery


Harvest descriptions of the hierarchy and topics


Load properties and relationships into the repository


Generate a table of contents and index on request


Query the repository for topics matched by the current filter


Insert links into topic pages on request


Query the repository for links matched by the current filter


Repository doesn’t need to store pages

repository

DITA topics

and maps

HTML

pages

load properties

and relationships

generate TOC and index
and insert links into pages

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Demo


DITA topics and map viewed from a repository

Technologies used


XSLT, RDF, JSP / Java, HTML

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Processing solution: dynamic navigation


For each user, maintain a set of values for the properties that define
the user’s interest

Values might include product, platform, user role, user experience, …

Scope the set of topics relevant to the organization and type of user

Filter the topics within the scope for this user’s current interest


Check each topic’s properties against the properties for the user

When the table
-
of
-
contents or index listing is generated

When the search engine returns a list of search results

When links are inserted into a topic


Other benefits of dynamic navigation

Multiple hierarchical views

Dynamically generated container topics

Position
-
specific synchronization



IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Summary


You can get started with dynamic navigation now



Refactor your content

Break up narrative sequences into context
-
free DITA topics

Define DITA maps to assemble the topics into deliverables

Specify properties, especially for topics that are the root of a branch in the
table of contents


Use topic properties to drive dynamic navigation

Acquire an off
-
the
-
shelf Content Management system

Create a framework for deployable information, possibly using Semantic
Web technologies

IBM User Technology

Dynamic Navigation in DITA

© 2004 IBM Corporation

Learning more


About DITA

Cover page
-

http://xml.coverpages.org/dita.html

Introduction
-

http://www
-
106.ibm.com/developerworks/xml/library/x
-
dita1/

Forum
-

news://news.software.ibm.com:119/ibm.software.developerworks.xml.dita

OASIS Technical Committee
-

http://www.oasis
-
open.org/committees/dita


About Semantic Web technologies

RDF standard
-

http://www.w3.org/RDF/

RDF resources
-

http://www.ilrt.bris.ac.uk/discovery/rdf/resources/

IBM RDF toolkit
-

http://www.alphaworks.ibm.com/tech/snobase

TopicMaps standard
-

http://www.topicmaps.org/

TopicMaps Cover page
-

http://www.oasis
-
open.org/cover/topicMaps.html