Making the Move to Information Architecture Alan Houser Principal Consultant and Trainer Tel: 412.363.3481 [email_address] www.groupwellesley.com Group Wellesley, Inc.

Making the Move to Information Architecture

What you will learn What is information architecture Why is information architecture important Approaches to information architecture Information architecture in DITA

What is information architecture

Why is information architecture important

Approaches to information architecture

Information architecture in DITA

What we will not discuss Complex terms that nobody understands

Complex terms that nobody understands

What is information architecture? “… Science of expressing a model or concept for information” (Wikipedia) All organizations use information architecture. Some more formally than others.

“… Science of expressing a model or concept for information” (Wikipedia)

All organizations use information architecture. Some more formally than others.

Why information architecture? Business requirements – time-to-market, reuse, efficiency in authoring, translation, publishing, content management. User requirements – usability, predictability, findability, consistency

Business requirements – time-to-market, reuse, efficiency in authoring, translation, publishing, content management.

User requirements – usability, predictability, findability, consistency

Before information architecture Books and book-like structures Ad hoc mechanisms for defining and organizing content Little control over content lifecycle

Books and book-like structures

Ad hoc mechanisms for defining and organizing content

Little control over content lifecycle

After information architecture Topics with named types and consistent, predictable internal structure Formal ways to associate metadata (properties, classes) with topics Formal ways to define topic collections Formal ways to define relationships, structures, hierarchies among topics

Topics with named types and consistent, predictable internal structure

Formal ways to associate metadata (properties, classes) with topics

Formal ways to define topic collections

Formal ways to define relationships, structures, hierarchies among topics

Ad hoc versus formal information architecture Auto-generated navigation based on structures Hard-coded navigation Formal types (task, concept, reference) Ad hoc types Map file TOC Topic Section Task analysis Outline Formal information architecture Ad hoc information architecture

Overview of DITA design Roots of DITA: minimalist approach

Roots of DITA: minimalist approach

DITA goals Provide task-oriented documentation Provide navigation and accessibility mechanisms Minimize amount of content provided to support your product or service Maximize usability Maximize process efficiency

Provide task-oriented documentation

Provide navigation and accessibility mechanisms

Minimize amount of content provided to support your product or service

Maximize usability

Maximize process efficiency

What is DITA? Darwin Information Typing Architecture An architecture that supports authoring, managing, and publishing topic-oriented content. Why DITA? Companies are looking for publishing solutions that facilitate information re-use, reduce time-to-market, improve management and maintainability, and provide the capability to deliver highly usable technical content.

Darwin Information Typing Architecture

An architecture that supports authoring, managing, and publishing topic-oriented content.

Why DITA?

Companies are looking for publishing solutions that facilitate information re-use, reduce time-to-market, improve management and maintainability, and provide the capability to deliver highly usable technical content.

DITA architecture Topics – typed, reusable units of information Specialization mechanism to create new topic types Maps define topic collections Content reuse at topic and fragment level Metadata-based content filtering

Topics – typed, reusable units of information

Specialization mechanism to create new topic types

Maps define topic collections

Content reuse at topic and fragment level

Metadata-based content filtering

Basic DITA information unit Should be stand-alone, usable out of context No formal restriction on topic length Generic "topic" type Specialized topic types: task, concept, reference DITA Topic

Basic DITA information unit

Should be stand-alone, usable out of context

No formal restriction on topic length

Generic "topic" type

Specialized topic types: task, concept, reference

Structure of a DITA Topic <topic> <title/> <titlealts/> <shortdesc/> <prolog/> <body/> <related-links/> </topic>

Structure of a DITA Task <task> <title/> <titlealts/> <shortdesc/> <prolog/> <taskbody/> <related-links/> </task>

Structure of a DITA Task (continued) <taskbody> <prereq/> <context/> <steps> <step><cmd> </cmd></step> <step><cmd> </cmd></step> … </steps> <result/> <example/> <postreq/> </taskbody>

Define topic sequences, hierarchies, groups Define topic sets and structure for publishing Define topic sets for project management and authoring responsibility Define navigation structures Augment and override topic-level metadata DITA Maps

Define topic sequences, hierarchies, groups

Define topic sets and structure for publishing

Define topic sets for project management and authoring responsibility

Define navigation structures

Augment and override topic-level metadata

<map title = &quot;Using your Acme Cell Phone&quot;> <topicref href=&quot;answer_call.xml&quot;/> <topicref href=&quot;attach_battery.xml&quot;/> <topicref href=&quot;change_case.xml&quot;/> <topicref href=&quot;charge_battery.xml&quot;/> </map> A basic DITA map file

<map title = &quot;Using your Acme Cell Phone&quot;>

<topicref href=&quot;answer_call.xml&quot;/>

<topicref href=&quot;attach_battery.xml&quot;/>

<topicref href=&quot;change_case.xml&quot;/>

<topicref href=&quot;charge_battery.xml&quot;/>

</map>

Expressing topic hierarchies <topicref> elements can be nested to express topic hierarchies in navigation and output: <topicref href = &quot;maintaining_battery&quot;> <topicref href = &quot;charge_battery.xml&quot;/> <topicref href = &quot;attach_battery.xml&quot;/> <topicref href = &quot;detach_battery.xml&quot;/> <topicref href = &quot;replace_battery.xml&quot;/> </topicref>

<topicref> elements can be nested to express topic hierarchies in navigation and output:

<topicref href = &quot;maintaining_battery&quot;>

<topicref href = &quot;charge_battery.xml&quot;/>

<topicref href = &quot;attach_battery.xml&quot;/>

<topicref href = &quot;detach_battery.xml&quot;/>

<topicref href = &quot;replace_battery.xml&quot;/>

</topicref>

Expressing headings within a map Use <topichead> to provide title for a group of <topicref> elements. Title is rendered in output. <topichead navtitle=&quot;Maintaining your battery&quot;> <topicref href=&quot;attach_battery.xml&quot;/> <topicref href=&quot;charge_battery.xml&quot;/> <topicref href=&quot;detach_battery.xml&quot;/> <topicref href=&quot;replace_battery.xml&quot;/> </topichead>

Use <topichead> to provide title for a group of <topicref> elements. Title is rendered in output.

<topichead navtitle=&quot;Maintaining your battery&quot;>

<topicref href=&quot;attach_battery.xml&quot;/>

<topicref href=&quot;charge_battery.xml&quot;/>

<topicref href=&quot;detach_battery.xml&quot;/>

<topicref href=&quot;replace_battery.xml&quot;/>

</topichead>

Overriding topic headings within a map Use navtitle attribute to override topic titles for navigation. Must also set locktitle attribute to &quot;yes&quot;. <topichead navtitle=&quot;Battery&quot;> <topicref href=&quot;charge_battery.xml&quot; navtitle=&quot;Charge&quot; locktitle=&quot;yes&quot;/> <topicref href=&quot;attach_battery.xml&quot; navtitle=&quot;Attach&quot; locktitle=&quot;yes&quot;/> <topicref href=&quot;detach_battery.xml&quot; navtitle=&quot;Detach&quot; locktitle=&quot;yes&quot;/> </topichead>

Use navtitle attribute to override topic titles for navigation. Must also set locktitle attribute to &quot;yes&quot;.

<topichead navtitle=&quot;Battery&quot;>

<topicref href=&quot;charge_battery.xml&quot; navtitle=&quot;Charge&quot; locktitle=&quot;yes&quot;/>

<topicref href=&quot;attach_battery.xml&quot; navtitle=&quot;Attach&quot; locktitle=&quot;yes&quot;/>

<topicref href=&quot;detach_battery.xml&quot; navtitle=&quot;Detach&quot; locktitle=&quot;yes&quot;/>

</topichead>

Overriding topic-level metadata DITA 1.0 provides 4 attributes to support topic filtering: audience , platform , product , otherprops . These are typically set in the topic file, but can be set or overridden in the map file. <topic audience=&quot;administrator&quot;> … </topic> <topicref href=&quot;troubleshooting.xml&quot; audience=&quot;user&quot; /> DITA 1.1 allows you to specialize the props attribute to provide your own attribute &quot;labels&quot;.

DITA 1.0 provides 4 attributes to support topic filtering: audience , platform , product , otherprops . These are typically set in the topic file, but can be set or overridden in the map file.

<topic audience=&quot;administrator&quot;> … </topic>

<topicref href=&quot;troubleshooting.xml&quot; audience=&quot;user&quot; />

DITA 1.1 allows you to specialize the props attribute to provide your own attribute &quot;labels&quot;.

Sounds like a good idea. Let’s go! Conventional approach to DITA migration Analyze legacy documents &quot;Chunk&quot; legacy content Assign topic types Rewrite content as necessary Convert content to markup Organize using DITA map files

Conventional approach to DITA migration

Analyze legacy documents

&quot;Chunk&quot; legacy content

Assign topic types

Rewrite content as necessary

Convert content to markup

Organize using DITA map files

A better approach Task-based approach Perform task analysis Determine supporting concept and reference topics Create organizing structure: sequences, hierarchies, groups Pull topics from legacy documentation as needed Write to fill the holes Throw the rest (of your legacy content) away

Task-based approach

Perform task analysis

Determine supporting concept and reference topics

Create organizing structure: sequences, hierarchies, groups

Pull topics from legacy documentation as needed

Write to fill the holes

Throw the rest (of your legacy content) away

Task analysis methodologies GOMS (Goals, Operators, Methods, Selection) and similar methodologies (Card, Moran, Newell) Card sorting Post-it notes Mind-mapping applications

GOMS (Goals, Operators, Methods, Selection) and similar methodologies (Card, Moran, Newell)

Card sorting

Post-it notes

Mind-mapping applications

Contact Us! We hope you enjoyed this presentation. Please feel free to contact us: Alan Houser [email_address] Group Wellesley, Inc. 933 Wellesley Road Pittsburgh, PA 15206 USA 412-363-3481 www.groupwellesley.com

We hope you enjoyed this presentation. Please feel free to contact us:

Alan Houser [email_address] Group Wellesley, Inc. 933 Wellesley Road Pittsburgh, PA 15206 USA 412-363-3481 www.groupwellesley.com