DITA Quick Start Webinar Series: Getting Started with Information Architecture


Published on

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

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

DITA Quick Start Webinar Series: Getting Started with Information Architecture

  1. 1. DITA Information Architecture Katriel Reichman, Suite Solutions
  2. 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. 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. 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. 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. 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. 7. Let’s get started
  8. 8. Support ISO Labeling: Requirements • Requirements • Color • Statement • Icon • Body • Choose markup for: • Notice • Danger • Warning • Caution type Icon: what could happen body
  9. 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. 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. 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. 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. 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. 14. What was troubleshooting specialized from? • Definition List • What would be the benefits of specializing? • What would be the drawbacks?
  15. 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. 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. 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. 18. Let’s take stock
  19. 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. 20. Questions? Feel free to be in contact: katrielr@suite-sol.com
  21. 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