making the move to information architecture
DESCRIPTION
Presented at DocTrain East 2007 Conference by Alan Houser, Group Wellesley -- Many documentation departments use loosely-defined or ad hoc standards for developing and delivering technical content. In many organizations, writers are judged by the volume of content that they produce. The larger the manual or help system, the more effective the writer. A fatter manual is considered to be a better manual. In the face of todays increasingly challenging business requirements, including increasing information re-use and decreasing time-to-market, these ad hoc methodologies and old-fashioned standards quickly break down. There is no positive correlation between page or topic count and usability. Higher page or topic counts mean higher maintenance, translation, and production costs. Furthermore, information developed without a formal information architecture is difficult to manage, difficult to publish, and difficult to re-use. To meet today’s business requirements, many organizations are adopting formal information architectures. A formal information architecture can bring many benefits, including increased writer efficiency, increased documentation usability, increased information re-use, and decreased cost of production. The most successful of these architectures embody the following concepts: * they are based on a tested communication strategy (in the case of DITA, the minimalist documentation strategy) * they include a formal analysis of the product or service being documented (e.g., a task analysis) * they define multiple information types * they define a way to define collections of those information types What does an information architecture lookӔ like? How does using an information architecture differ from ad hoc information development strategies? We will see how one popular information architecture (DITA) defines both topics and topic collections. We will also discuss effective strategies for adopting a formal information architecture, and for migrating legacy content to a formal information architecture. Although examples will be based on DITA, concepts will apply to any information architecture or structured authoring environment.TRANSCRIPT
Alan HouserPrincipal Consultant and Trainer
Tel: [email protected]
Making the Move to Information Architecture
Group Wellesley, Inc.
What you will learn
• 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
What is information architecture?
• “…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
Before information architecture
• 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
Ad hoc versus formal information architecture
Ad hoc information architecture
Formal information architecture
Outline Task analysis
Section Topic
TOC Map file
Ad hoc types Formal types (task, concept, reference)
Hard-coded navigation Auto-generated navigation based on structures
Overview of DITA design
• 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
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.
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
• 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
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
<map title = "Using your Acme Cell Phone"> <topicref href="answer_call.xml"/> <topicref href="attach_battery.xml"/> <topicref href="change_case.xml"/> <topicref href="charge_battery.xml"/></map>
A basic DITA map file
Expressing topic hierarchies
• <topicref> elements can be nested to express topic hierarchies in navigation and output:
<topicref href = "maintaining_battery"> <topicref href = "charge_battery.xml"/> <topicref href = "attach_battery.xml"/> <topicref href = "detach_battery.xml"/> <topicref href = "replace_battery.xml"/></topicref>
Expressing headings within a map
• Use <topichead> to provide title for a group of <topicref> elements. Title is rendered in output.
<topichead navtitle="Maintaining your battery"> <topicref href="attach_battery.xml"/>
<topicref href="charge_battery.xml"/> <topicref href="detach_battery.xml"/>
<topicref href="replace_battery.xml"/></topichead>
Overriding topic headings within a map
• Use navtitle attribute to override topic titles for navigation. Must also set locktitle attribute to "yes".
<topichead navtitle="Battery"> <topicref href="charge_battery.xml"
navtitle="Charge" locktitle="yes"/> <topicref href="attach_battery.xml"
navtitle="Attach" locktitle="yes"/> <topicref href="detach_battery.xml"
navtitle="Detach" locktitle="yes"/></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="administrator"> … </topic>
<topicref href="troubleshooting.xml" audience="user" />
• DITA 1.1 allows you to specialize the props attribute to provide your own attribute "labels".
Sounds like a good idea. Let’s go!
Conventional approach to DITA migration
• Analyze legacy documents
• "Chunk" 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 analysis methodologies
• 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 [email protected]
Group Wellesley, Inc.933 Wellesley RoadPittsburgh, PA 15206USA412-363-3481www.groupwellesley.com