Presented at DocTrain East 2007 by Joe Gelb, Suite Solutions -- Designing, building and maintaining a coherent information architecture is critical to proper planning, creation, management and delivery of documentation and training content. This is especially true when your content is based on a modular or topic-based model such as DITA and SCORM or if you are migrating to such a model. But where to start? Terms such as taxonomy, semantics, and ontology can be intimidating, and recognized standards like RDF, OWL, Topic Maps (XTM) and SKOS seem so abstract. This pragmatic workshop will provide an overview of the standards and concepts, and a chance to use them hands-on to turn the abstract into tangible skills. We will demonstrate how a well-designed information architecture facilitates reuse and how the information model is integrally connected to conditional and multi-purpose publishing. We will introduce an innovative, comprehensive methodology for information modeling and content development called SOTA Solution Oriented Topic Architecture. SOTA does not aim to be yet another new standard, but rather a concrete methodology backed up with open-source and accessible tools for using existing standards. We will demonstrate ֖and practice—hands-on—how this powerful methodology can help you organize and express information, determine which content actually needs to be created or updated, and build documentation and training deliverables from your content based on the rules you define. This workshop is essential for successfully implementing topic models like DITA and SCORM, multi-purpose conditional publishing, and successfully facilitating content reuse.

1. Understanding Information
Architecture
Doctrain East, October 2007
Joe Gelb
President, Suite Solutions

2. Main Training Topics
Introductions: Who is this guy?
What is information architecture?
Why is it important?
Introduction to key concepts and standards
Methodology for developing information
architecture for techdocs and training
Let’s try it

3. Who is this guy?
Background in Mechanical Engineering
CAD/CAM
Production process planning
CTO for a leading techdoc provider and technology
vendor
Built and managed professional services group
Responsible for design, development and
implementation of DB and publishing applications
for tech and reference publications, including CMS
Left to form independent consulting and
implementation group

4. Main Training Topics
Introductions: Who is this guy?
What is information architecture?
Why is it important?
Introduction to key concepts and standards
Methodology for developing information
architecture for techdocs and training
Let’s try it

5. What is Information Architecture
The science of expressing a model or concept for
information
Used for activities that require expressions of
complex systems
Consists of:
Structural design of shared information
environments
Organizing and labeling information to support
usability and findability
From Wikipedia

6. What is IA for us?
Method for organizing documentation and training
resources – text, media – into an overarching
knowledge model
The knowledge model is created and maintained
separate from the actual content – like creating a
global index
Allows us to provide access to the information
based on the model of the knowledge it contains
Steve Newcombe
Simple level: Organization of content by hierarchy,
relationships
Next level: Organization of subjects, and relate
content to those subjects

7. Why it is it important for us?
Best practices for technical content development
based on topic-oriented content architecture
Topic-oriented content = modular = component-
based documentation
Instead of creating deliverables, we create discrete
topics of information
Need better methodologies to plan, create,
manage, localize, publish, deliver and find content
Why?
Sheer volume of individual resources
Allows us to reap the benefits

8. Topic-Based Content
Topics
Each topic answers a single question
Only enough information to understand one
concept, perform one procedure or provide one
set of reference information
Maps
Assemble topics into deliverables
Define relationships between topics
Standards being adopted
DITA
SCORM
S1000D

9. Business Advantages of
Topic-based Content
More efficient authoring
Reuse content in multiple deliverables
Easier to maintain content
Topic architecture and DTD promotes
minimalization
Easier to customize deliverables:
Conditionalization on the map level, topic level,
and element level
Automated publishing

10. Business Advantages of
Topic-based Content
Reduce review time
Review topics as they are ready
SMEs focus on single topics instead of entire
deliverables
Review topics once, even if they appear multiple
times in multiple deliverables
Reduce localization costs
Only send new and updated topics for translation
Translate topics as they are ready: no need to wait
for entire deliverable to be completed
Reduce time to market:
Quicker authoring, review, translation, publishing

11. Overview of DITA
Darwin Information Typing Architecture
OASIS standard
Open Source: DTDs, schemas, DITA-OT
are free
Not just a DTD: an architecture for
designing, authoring, managing and
publishing content

12. Overview of DITA
Facility for customization within the
standard: specialization (thus Darwin)
Facilitates documentation minimalization
with semantic tagging
Open Source Toolkit (DITA-OT) for
producing outputs
Active user and development community:
reaching critical mass

13. DITA Facilitates Reuse
Assemble topics into deliverables
Reference topic elements within other
topics: conrefs (content references)
Conditionalize content within topics using
conditional attributes
Filter content based on conditions to get
multi-purpose outputs
(conditional processing)
Manage links separately from the content
using relationship tables

14. DITA Maps: Assembling
Topics into Deliverables
Assemble any number of topics into
sequences for print or online delivery
Organize topics into a hierarchy
Based on context and position, not the
topics themselves
Use sub-maps within maps
Allows you to create building blocks
Topics can occur in more than one position
in the same map

15. DITA Maps: Assembling
Topics into Deliverables
Can create different types of maps:
Solution-oriented
How products and procedures work together
Task-oriented
How to accomplish a specific goal
Feature-oriented
What does a product or component do

16. Where Does IA Fit Into This
Hierarchical and sequential organization of topics into
deliverables:
DITA Maps, SCORM manifests
Definition of relationships between topics:
DITA relationship tables, related links
Overarching knowledge model:
XTM, SKOS, DITA Taxonomy specialization
Helps organize creation and sharing of content
Determines valid use of conditionalization in the
content – topics and maps
Allows usage of standard tools for navigating and
searching content: semantic web

17. Main Training Topics
Introductions: Who is this guy?
What is information architecture?
Why is it important?
Introduction to key concepts and standards
Methodology for developing information
architecture for techdocs and training
Let’s try it

18. What is Semantic Web?
Semantics: the study of meaning
Semantic technologies: help separate meaning from
the documentation content itself based on open
standards
Allows computers to interpret and process the meaning
of a document
Semantic Web: framework that allows information to be
identified and reused across application, organization
and community boundaries
Meaning is represented using ontologies and provide
reasoning through relationships, rules, logic and
conditions expressed in the ontologies

19. What’s an Ontology?
- Dr. Leo Obrst, MITRE Information Semantics Group
Terms used to describe and represent an area of
knowledge – subject matter
Model for the meaning of those terms
Vocabulary and the meaning of that vocabulary
For us, that means standardized index, glossary,
conditional tags/conditional attribute values
Used by people, databases and applications to
navigate, identify and share information in a specific
domain (specific area of knowledge)
For us, that means better planning and content
reuse on the authoring side and better delivery on
the production side

20. What are Semantic
Technologies
Global naming schemes: URI (identifier)
Standard syntax to describe data and properties of the
data: RDF
Standard way to describe relationships between data:
Ontologies defined with:
OWL Web Ontology Language
XML Topic Maps (XTM)
SKOS – Simple Knowledge Organization System

21. Spectrum of Ontology

22. RDF: Resource Description
Framework
Standard model for representing information
Standard syntax to describe and exchange data
Defines a graph of relations represented by
object-attribute-value triples
That is: Object O has an attribute A with value V

23. Sample RDF XML
Object type: Component
Object identifier: C89722A8-…-68F01FCD2ADE
Attributes
Title
Release date
Part Number, Part Name

24. RDF Graphical Representation

25. OWL: Ontology Working
Language
Describes relations between classes of information
Based on classes, individuals and properties
Class: a concept or subject in a domain; can be
organized hierarchically
Individual: instance of a class

26. OWL: Ontology Working
Language
Properties:
Object: relate individuals to other individuals
Datatype: relate individuals to data values
(numbers, strings, etc.)
Functional: property takes only one value (e.g.
age)
Inverse Functional: Two individuals cannot have
the same value (e.g. social security number)
Symmetric: If A links to B, then infer that
B links to A (e.g. siblings)
Transitive: If A links to B and B links to C, then
infer that A links to C

27. OWL: Ontology Working
Language
“The Future of the Web is Semantic,” Naveen Balani, 18 Oct 2005

28. Topic Maps (XTM)
Semantic knowledge model to express an ontology
ISO standard; can also be expressed as XML
Topic
Represents a subject or concept
Categorized by Type
Map
Associations: relationships between topics
Occurrences: link between information resources and
the subjects that they express something about

29. Graphical Representation of a
Topic Map
“The TAO of Topic Maps,” Steve Pepper

30. SKOS: Simple Knowledge
Organization System
Standard for modeling an ontology
Similar to Topic Maps, however it is expressed using
RDF, the accepted syntax of expression for the
semantic web
Thus, SKOS bridges the gap between traditional
indexing and formal ontologies for the semantic web
Define subjects and if desired, organize them into a
taxonomy (i.e. hierarchy)
Classify content to indicate its subject
DITA Taxonomy specialization allows you to maintain
the ontology in DITA and transform it into SKOS RDF
for processing and use with standard tools

31. SKOS: Simple Knowledge
Organization System
“Subject Classification with DITA and SKOS,” Hennum, Anderson and Bird, October 2005

32. SKOS: Simple Knowledge
Organization System
Assembling a deliverable from the subject and content maps
“Subject Classification with DITA and SKOS,” Hennum, Anderson and Bird, October 2005

33. SKOS: Simple Knowledge
Organization System
RDF expression of a SKOS ontology
“Connecting the Dots: Relationship and Relevance with DITA Maps,” Hennum

34. Main Training Topics
Introductions: Who is this guy?
What is information architecture?
Why is it important?
Introduction to key concepts and standards
Methodology for developing information
architecture for techdocs and training
Let’s try it

35. Solution Oriented Content
Development
Develop a High Level Information Architecture
Create a knowledge model of subjects
encompassing:
All products, features, system components
All life-cycle stages
From that model, compile lists of content to be
created to express the knowledge model
Compile content to form maps representing
documentation deliverables
DITA Maps
SCORM Manifests

36. Examples of Subjects
Type Subjects
Products Servers: S1, S2, S3
Endpoints: E1, E2, E3
Peripherals: P1, P2, P3
Platforms Windows, Unix, Linux, Macintosh
Supported
Assemblies Assy1, Assy2, Assy3
Parts P101, P102, P103
Life Cycle Design
Sell: Demos, Positioning, Related Products, Related Services,
Strategy, Target Market
Implement: Initialize, Install, Configuration, Training
Use: End Use, Administer
Maintain: Troubleshoot, Optimize, Service, Maintenance
Other Subject Types: Features, Tasks, Interfaces, Screens, Use Cases, User Roles, Legal Info

37. Subject Associations
Define relationships between subject types to help
compile the full list of subjects to be documented
Solution System Component
Product Platform Supported
Product Feature
Feature Task
Task Interface
Task Life Cycle
Task User Role
Product Assembly
Assembly Part

38. Build Your Own Ontology
List Solutions your company offers
For each Solution: list System Components
For each Product:
Associate with System Components
Associate with Platforms Supported
List Features
For each Feature:
Associate with Platforms Supported
Associate with User Roles
List Tasks
For each Task:
List Screens
Associate with Life Cycle Stage
Associate with User Roles

39. Content Resources
Different types of content resources are
used to express information about the
subjects
DITA Task
DITA Reference
DITA Concept
Illustration
Drawing
Flash
Video
Presentation

40. Generate List of Content to be
Created
Set rules: Topics needed to express each subject
For Each: Create Content Topic:
Product Overview (DITA Concept), Legal license / liability /
warrantee
Feature Description, Use Case
Task Procedure (DITA Task), safety instruction
Screen List of buttons and fields (DITA Reference)
Assembly Installation Task, Maintenance Task, List of Parts
Part Description, Supplier, Replacement Part, Diagram

41. Author Content
For each content instance, author knows the topic
to be described and the characteristics
Example:
Procedure: Configuring Server Ports (DITA Task)
Characteristics:
Product: Server S1
Task: Configure Server Ports
User Roles: Administrator, Implementer
Interface: Admin
Screen: Port Configuration
Life Cycle Stage: Installation, Configuration
Platform: Windows, Unix, Linux
Related Content:
Screen element reference, Screen capture

42. Generate Deliverables
Set rules for each type of deliverable to create maps
Deliverable Contents
Installation Product Overview, Legal References, Installation and
Guide Configuration Procedures associated with
User Role=Implementer
Admin Guide Product Overview, Legal References
For each interface associated with Admin, Implementer,
Technician
For each screen, include screen reference
For each Task associated with life cycle stage: Installation,
Configuration, Administer, Troubleshoot
Include Procedures (DITA Task)

43. Generate Deliverables
Set rules for each type of deliverable to create maps
Deliverable Contents
User Guide Product Overview, Legal References
Getting Started
For each Task associated with User Role: End User, Life
Cycle: Installation, Configuration, include all procedures
Features
For each Feature
Include Feature Description
For each Task associated with Life Cycle: Use, User Role:
End User include Procedure

44. Main Training Topics
Introductions: Who is this guy?
What is information architecture?
Why is it important?
Introduction to key concepts and standards
Methodology for developing information
architecture for techdocs and training
Let’s try it

45. Let’s Give it a Try
1. Create a list of subject types:
Solutions, products, components, features,
procedures …
2. What kinds of relationships are there
between the different kinds of subjects?
3. Note the relationships between the
different subjects
4. Compile your list of content to create
5. Develop rules for how to build a deliverable

46. Good Luck
!

47. End of Understanding Information
Architecture