In this webinar we will discuss a range of factors which you need to consider in the information architecture stage, including: * Determining which topic types to use * Selecting semantically appropriate tags * Choosing elements that will enable fastest content creation and best presentation * Identifying any business case for specialization * Enabling reuse through appropriate use of variables, keyref, conref and more * Applying conditions to enable focused content limited to “need to know”, without destroying writer productivity * Developing an approach for accessing related information using relationship tables and other mechanisms View the webinar video on our Youtube channel http://www.youtube.com/watch?v=Aq6hcXwe02A

1. DITA Information Architecture
Katriel Reichman, Suite Solutions

2. Who am I?
Katriel Reichman
• Background in technical documentation, content
management systems, structured content and DITA
• Early and senior member of the Suite Solutions team
• Given many public and private training seminars over
the past five years
• Extensive expertise implementing DITA and CMS
solutions for a wide variety of organizations
• Information architecture and customer training at Suite
Solutions
• Help companies get it right the first time

3. About Suite Solutions
Our Vision: Enable companies to engage their customers by providing quick
access to relevant information
• Help companies get it right the first time
• XML-based Authoring/Publishing Solutions
• Enterprise Intelligent Dynamic Content: SuiteShare
• Consultancy, Systems Integration, Application Development
• Cross-Industry Expertise
• High Tech, Aerospace & Defense
• Healthcare, Discrete Manufacturing
• Blue Chip Customer Base
• Hundreds of Person Years of Experience on Staff

4. Why Information Architecture
• Bridge the gap from plan to DITA implementation
• Increase the effectiveness of your DITA content
• Focused content
• Optimized for delivery channel
• Consistent, minimalist and other measures
• Reduce total costs for content
• Creation
• Updates (maintenance)
• Publishing
• Translations
• Enable support for the fullest range of current and
future publishing needs

5. What We Think About in Information
Architecture (IA)
• In IA, a lot of thought is given to a range of factors, including:
• what topic types should be used (for example, machine industry
tasks or strict task topic types)
• what specializations may be needed
• selecting semantically appropriate elements
• choosing elements for fastest content creation, best presentation
• enabling reuse (through use of variables/keyref, conref and more)
• applying conditions for “need to know” and writer productivity
• developing a related information approach
• minimizing translation cost and enabling pain free translation

6. Cases that we’ll cover today
• Support ISO Labeling Requirements
• To get an idea of these requirements, safetylabelsolutions.com.
(The full ISO standards require payment to access)
• Document a UI with multiple clicks required by the user
• Provide troubleshooting information
• Automate links to your external web site
• Reduce costs through automation
• Translation
• Maintenance Costs

7. Let’s get started

8. Support ISO Labeling:
Requirements
• Requirements
• Color
• Statement
• Icon
• Body
• Choose markup for:
• Notice
• Danger
• Warning
• Caution
type
Icon: what
could happen
body

9. Support ISO Labeling:
Solution w/o Specialization
• Each <hazardstatement> has two dimensions, indicated by attributes:
• type: the level of hazard (notice, danger, caution or warning)
• othertype: the type of hazard (asphyxiation, biohazard, etc)
• Sample markup:
• <hazardstatement othertype="danger" type="corrosion">
• <messagepanel>
• <typeofhazard>Roof can collapse if corrosion damages supporting
rods.</typeofhazard>
• <consequence>You can be crushed by the roof.</consequence>
• <howtoavoid>Apply W40 anti-corrosion lubricant every week to all
exposed surfaces.</howtoavoid>
• </messagepanel>
• </hazardstatement>

10. UI requires multiple clicks
• User needs to navigate through a series of
• Actions, menus, tabs, or windows
• Choose the markup that you need
• What benefits does semantic markup confer?

11. Provide troubleshooting
• How would you choose elements for this scenario
• Each observation (symptom) is treated independently.
 For example, car won’t start
• Each observation is assigned at least one possible cause
 For examples:
 No fuel in the car
 Battery dead
 Code not entered
 Code has expired
• Each cause has one or more suggested actions
 For examples:
 Put gas in the car
 Connect to a charger
 Type in the code
 Check expiration date on your code

12. Put troubleshooting in a table?
• Could you put the troubleshooting content in a
• table?
• definition list (DL)?
• What would the considerations be for deciding if that was sufficient?

13. Suggestion for troubleshooting
• <title>enter your observation here, such as: Fish is swimming sideways</title>
• <tsobservation>enter any details about the observation here</tsobservation>
• <trbody>
• <tl>
• <tlentry>
• <tscause>Water temperature is too high. </tscause>
• <tsaction><note>“Too high” depends on the fish species.</note>Reduce water
temperature.</tsaction>
• </tlentry>
• <tlentry>
• <tscause>Too much chlorine in the water.</tscause>
• <tsaction>Add anti-chlorine tablets</tsaction>
• <tsaction>Replace water with distilled water from a pharmacy.</tsaction>
• </tlentry></tl></trbody>

14. What was troubleshooting specialized
from?
• Definition List
• What would be the benefits of specializing?
• What would be the drawbacks?

15. Reduce cost through automation
• Goals:
• Reduce costs through automation
 Translation
 Maintenance Costs
• Automate links to the publication
• The use case:
• Content refers to other publications
 Such as API Guide, Periodic Maintenance
Instructions
• The names of the other publications
change from time to time
• Lists of “publications that you need” must
be provided
• What markup would you use?

16. Reduce cost through automation
• Automatically link to the published content for any element that
represents a document
• Using <sku> (an element specialized from <ph>
• Sample markup:
• <sku keyref=“178PZ"><?xm-replace_text Weekly Preventive
Maintenance?></sku>
• How does this compare to
• Manual entry of publications in the <reqcontp> element?
• What happens when the name of a publication changes?
• What happens when a new publication is referenced in the
content?

17. Automate links to your external web site
• Your content offers an opportunity to:
• Sell consumables (e,g. chemicals, toner, fish food)
• Order additional services
• The goal: automate links to realize the opportunity
• What markup would you choose?
• How would a potential sales opportunity be identified?
• How would the link syntax be available to the publishing engine?
• Suggestion (same as for publications!):
 Using <sku> (an element specialized from <ph>
• Could you get automated links with using a special element?

18. Let’s take stock

19. What We Have Learned Today
• Selecting topic types
• Determining if a specializations is called for
• Selecting semantically appropriate elements for UI docs
• Choosing elements for troubleshooting content
• Balancing considerations for:
• Fastest content creation
• Best presentation
• Lowest cost
 Implementation
 Maintenance
 Translations
• Is there more to learn? For sure. Suite Solutions is here to help.

20. Questions?
Feel free to be in contact: katrielr@suite-sol.com

21. Keep in Touch!
For additional information, contact:
Joe Gelb
solutions@suite-sol.com
U.S. Office EMEA Office
(609) 360-0650 +972-2-993-8054
www.suite-sol.com
For more great DITA information, follow us on LinkedIn:
http://www.linkedin.com/company/527916