Modular Documentation Bringing the Pieces Together Joe Gelb Suite Solutions

Modular Documentation Who is this Guy Challenges for TechDoc Groups What Is Information Architecture? Revising Processes

Who is this Guy

Challenges for TechDoc Groups

What Is Information Architecture?

Revising Processes

Who is this guy? Background in Mechanical Engineering Production process planning CTO at Live Linx Built and managed the conversion team Responsible for design, development and implementation of tools Left Live Linx in 2006 to form independent consulting and implementation group Focus on DITA, international presence

Background in Mechanical Engineering

Production process planning

CTO at Live Linx

Built and managed the conversion team

Responsible for design, development and implementation of tools

Left Live Linx in 2006 to form independent consulting and implementation group

Focus on DITA, international presence

Modular Documentation Who is this Guy Challenges for TechDoc Groups What Is Information Architecture? Revising Processes

Who is this Guy

Challenges for TechDoc Groups

What Is Information Architecture?

Revising Processes

Challenges of Documentation Groups Multi-purpose documents for multiple products, audiences, configurations, etc. Multi-channel publishing into many formats from the same source Reduce localization and desktop publishing costs Reuse content for multiple documents, across the organization and product lifecycle Provide more accessible, searchable, focused and updated content to internal and external customers

Multi-purpose documents for multiple products, audiences, configurations, etc.

Multi-channel publishing into many formats from the same source

Reduce localization and desktop publishing costs

Reuse content for multiple documents, across the organization and product lifecycle

Provide more accessible, searchable, focused and updated content to internal and external customers

Modular Documentation 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 Standards being adopted: DITA, S1000D, SCORM

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

Standards being adopted: DITA, S1000D, SCORM

Topic-Based Content Using DITA 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 using Maps Define relationships between topics in relationship tables

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 using Maps

Define relationships between topics in relationship tables

Advantages of Using DITA More efficient authoring Reuse content in multiple deliverables Easier to maintain content Topic architecture and semantic tags promotes minimalization Easier to customize deliverables: multi-purpose Conditional attributes for product, platform, audience, and user defined conditions Multi-channel, single source, automated publishing

More efficient authoring

Reuse content in multiple deliverables

Easier to maintain content

Topic architecture and semantic tags promotes minimalization

Easier to customize deliverables: multi-purpose Conditional attributes for product, platform, audience, and user defined conditions

Multi-channel, single source, automated publishing

Challenges of Technical Writers Overall pressure to increase efficiency and reduce redundancy Topic-based content requires a paradigm shift from deliverable-based content Instead of managing deliverables, need to manage discrete topics – may be thousands Need better methodologies to plan, create, classify, manage, localize, publish, deliver and find content TWs are becoming information architects…

Overall pressure to increase efficiency and reduce redundancy

Topic-based content requires a paradigm shift from deliverable-based content

Instead of managing deliverables, need to manage discrete topics – may be thousands

Need better methodologies to plan, create, classify, manage, localize, publish, deliver and find content

TWs are becoming information architects…

Modular Documentation Who is this Guy Challenges for TechDoc Groups Information Architecture Revising Processes

Who is this Guy

Challenges for TechDoc Groups

Information Architecture

Revising Processes

What is Information Architecture? The science (art?) 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 Method of organizing and labeling information From Wikipedia

The science (art?) 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

Method of organizing and labeling information From Wikipedia

What is IA for Documentation? 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 relating content to those subjects

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 relating content to those subjects

What is an Ontology? 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 - 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

Introducing: Topic Maps 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

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

Information Model Based on Topic Maps “ Subject Classification with DITA and SKOS,” Hennum, Anderson and Bird, October 2005

How can Topic Maps Help? Standardize subject matter, index and glossary Determine valid usage of metadata and applicability / effectivity values (DITA conditional attributes) Associative topic navigation, not just hierarchical Results in better planning and content reuse while authoring; robust filtering and navigation in our deliverables

Standardize subject matter, index and glossary

Determine valid usage of metadata and applicability / effectivity values (DITA conditional attributes)

Associative topic navigation, not just hierarchical

Results in better planning and content reuse while authoring; robust filtering and navigation in our deliverables

Modular Documentation Who is this Guy Challenges for TechDoc Groups Information Architecture Revising Processes

Who is this Guy

Challenges for TechDoc Groups

Information Architecture

Revising Processes

Traditional Method for Developing Content Deliverable-based: Determine deliverables needed for product Create an outline of topics needed Locate and reuse existing content; write everything else from scratch Using topic-oriented architecture: Create outline using map Link to existing topics; create space-holder topics for new content Maintain Master Topic List

Deliverable-based:

Determine deliverables needed for product

Create an outline of topics needed

Locate and reuse existing content; write everything else from scratch

Using topic-oriented architecture:

Create outline using map

Link to existing topics; create space-holder topics for new content

Maintain Master Topic List

Alternative Method using Information Architecture Solution Oriented Topic Architecture Create a knowledge model of subjects encompassing: All products, features, system components All product 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

Solution Oriented Topic Architecture

Create a knowledge model of subjects encompassing:

All products, features, system components

All product 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

Define Subjects and Types Example List Products and Solutions your company offers For each Product: List System Components List Features List Tasks List Life Cycle Stages For each Task: List Interfaces and Screens User Roles

List Products and Solutions your company offers

For each Product:

List System Components

List Features

List Tasks

List Life Cycle Stages

For each Task:

List Interfaces and Screens

User Roles

Define Relationship Types Define relationships between subjects Product  System Component Product  Platform Supported Product  Feature Feature  Task Task  Interface Task  Life Cycle Task  User Role System Component  Assembly

Define relationships between subjects

Product  System Component

Product  Platform Supported

Product  Feature

Feature  Task

Task  Interface

Task  Life Cycle

Task  User Role

System Component  Assembly

List Relationships For each Product: Associate with Platforms Supported Associate with Features For each Feature: Associate with Platforms Supported Associate with Tasks For each Task: Associate with Interfaces and Screens Associate with Life Cycle Stage Associate with User Roles

For each Product:

Associate with Platforms Supported

Associate with Features

For each Feature:

Associate with Platforms Supported

Associate with Tasks

For each Task:

Associate with Interfaces and Screens

Associate with Life Cycle Stage

Associate with User Roles

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

Design Sell: Demos, Positioning, Related Products, Related Services, Implement: Initialize, Install, Configuration, Training Use: End Use, Administer Maintain: Troubleshoot, Optimize, Service, Maintenance

Servers: S1, S2, S3 Endpoints: E1, E2, E3 Peripherals: P1, P2, P3

Assy1, Assy2, Assy3

P101, P102, P103

Windows, Unix, Linux, Macintosh

Determine Content Resources Different types of content resources are used to express information about the subjects Procedure / Task Concept / Description Reference Illustration Drawing Flash Video Presentation

Different types of content resources are used to express information about the subjects

Procedure / Task

Concept / Description

Reference

Illustration

Drawing

Flash

Video

Presentation

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

Set rules: Content types needed to express each subject

Description, Supplier, Replacement Part, Diagram

Installation Task, Maintenance Task, List of Parts

List of buttons and fields (DITA Reference)

Description, Use Case

Procedure (DITA Task), safety instruction

Overview (DITA Concept), Legal license / liability / warrantee

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

For each content instance, author knows the topic to be described and the characteristics via associations

Example: Procedure: Configuring Server Ports (DITA Task)

Characteristics / Associations:

Product: Server S1

User Roles: Administrator, Implementer

Interface: Admin

Screen: Port Configuration

Life Cycle Stage: Installation, Configuration

Platform: Windows, Unix

Related Content:

Screen element reference, Screen capture

Generate Deliverables Set rules for each type of deliverable to create maps 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) Admin Guide Product Overview, Legal References, Installation and Configuration Procedures associated with User Role=Implementer Installation Guide Contents Deliverable

Set rules for each type of deliverable to create maps

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)

Product Overview, Legal References, Installation and Configuration Procedures associated with User Role=Implementer

Generate Deliverables Set rules for each type of deliverable to create maps 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 User Guide Contents Deliverable

Set rules for each type of deliverable to create maps

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

Conclusion Information Architecture focuses on subject matter separately from the content First build your information model, then create your content topics to express that model ** All bases are covered! No more, no less Collect content topics into any combination of deliverables you need Deliverables can now be dynamically filtered, generated and navigated based on specific products, configurations, user roles, etc.

Information Architecture focuses on subject matter separately from the content

First build your information model, then create your content topics to express that model ** All bases are covered! No more, no less

Collect content topics into any combination of deliverables you need

Deliverables can now be dynamically filtered, generated and navigated based on specific products, configurations, user roles, etc.

Be in touch Your feedback and ideas are appreciated! Our team can help your organization evaluate and implement a solution suitable to your own requirements Joe Gelb [email_address] Tel: +972-993-8054

Your feedback and ideas are appreciated!

Our team can help your organization evaluate and implement a solution suitable to your own requirements