Modular Documentation Joe Gelb Techshoret 2009


Published on

Designing, building and maintaining a coherent content model is critical to proper planning, creation, management and delivery of documentation and training content. This is especially true when implementing a modular or topic-based XML standard such as DITA, SCORM and S1000D, and is essential for successfully facilitating content reuse, multi-purpose conditional publishing and user-driven content.
During this presentation we will review basic concepts and methods for implementing information architecture. We will then introduce an innovative, comprehensive methodology for information modeling and content development that employs recognized XML standards for representation and interchange of knowledge, such as Topic Maps and SKOS. In this way, semantic technologies designed for taxonomy and ontology development can be brought to bear for creating and managing technical documentation and training content, and ultimately impacting the usability and findability of technical information.

Published in: Business, Education
  • Be the first to comment

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

No notes for slide
  • When arrive: Ask about books and lunch Also ask about certificates and evaluations Turn off Skype Present Daily Schedule: 9-4 with a long break for lunch and two shorter breaks – one in morning, one in afternoon – mention lunch
  • Modular Documentation Joe Gelb Techshoret 2009

    1. 1. Modular Documentation Bringing the Pieces Together Joe Gelb Suite Solutions
    2. 2. Modular Documentation <ul><li>Who is this Guy </li></ul><ul><li>Challenges for TechDoc Groups </li></ul><ul><li>What Is Information Architecture? </li></ul><ul><li>Revising Processes </li></ul>
    3. 3. Who is this guy? <ul><li>Background in Mechanical Engineering </li></ul><ul><ul><li>Production process planning </li></ul></ul><ul><li>CTO at Live Linx </li></ul><ul><ul><li>Built and managed the conversion team </li></ul></ul><ul><ul><li>Responsible for design, development and implementation of tools </li></ul></ul><ul><li>Left Live Linx in 2006 to form independent consulting and implementation group </li></ul><ul><li>Focus on DITA, international presence </li></ul>
    4. 4. Modular Documentation <ul><li>Who is this Guy </li></ul><ul><li>Challenges for TechDoc Groups </li></ul><ul><li>What Is Information Architecture? </li></ul><ul><li>Revising Processes </li></ul>
    5. 5. Challenges of Documentation Groups <ul><li>Multi-purpose documents for multiple products, audiences, configurations, etc. </li></ul><ul><li>Multi-channel publishing into many formats from the same source </li></ul><ul><li>Reduce localization and desktop publishing costs </li></ul><ul><li>Reuse content for multiple documents, across the organization and product lifecycle </li></ul><ul><li>Provide more accessible, searchable, focused and updated content to internal and external customers </li></ul>
    6. 6. Modular Documentation <ul><li>Best practices for technical content development based on topic-oriented content architecture </li></ul><ul><li>Topic-oriented content = modular = component-based documentation </li></ul><ul><li>Instead of creating deliverables, we create discrete topics of information </li></ul><ul><li>Standards being adopted: DITA, S1000D, SCORM </li></ul>
    7. 7. Topic-Based Content Using DITA <ul><li>Topics </li></ul><ul><ul><li>Each topic answers a single question </li></ul></ul><ul><ul><li>Only enough information to understand one concept, perform one procedure or provide one set of reference information </li></ul></ul><ul><li>Maps </li></ul><ul><ul><li>Assemble topics into deliverables using Maps </li></ul></ul><ul><ul><li>Define relationships between topics in relationship tables </li></ul></ul>
    8. 8. Advantages of Using DITA <ul><li>More efficient authoring </li></ul><ul><ul><li>Reuse content in multiple deliverables </li></ul></ul><ul><ul><li>Easier to maintain content </li></ul></ul><ul><ul><li>Topic architecture and semantic tags promotes minimalization </li></ul></ul><ul><li>Easier to customize deliverables: multi-purpose Conditional attributes for product, platform, audience, and user defined conditions </li></ul><ul><li>Multi-channel, single source, automated publishing </li></ul>
    9. 9. Challenges of Technical Writers <ul><li>Overall pressure to increase efficiency and reduce redundancy </li></ul><ul><li>Topic-based content requires a paradigm shift from deliverable-based content </li></ul><ul><li>Instead of managing deliverables, need to manage discrete topics – may be thousands </li></ul><ul><li>Need better methodologies to plan, create, classify, manage, localize, publish, deliver and find content </li></ul><ul><li>TWs are becoming information architects… </li></ul>
    10. 10. Modular Documentation <ul><li>Who is this Guy </li></ul><ul><li>Challenges for TechDoc Groups </li></ul><ul><li>Information Architecture </li></ul><ul><li>Revising Processes </li></ul>
    11. 11. What is Information Architecture? <ul><li>The science (art?) of expressing a model or concept for information </li></ul><ul><li>Used for activities that require expressions of complex systems </li></ul><ul><li>Consists of: </li></ul><ul><ul><li>Structural design of shared information environments </li></ul></ul><ul><ul><li>Method of organizing and labeling information From Wikipedia </li></ul></ul>
    12. 12. What is IA for Documentation? <ul><li>Method for organizing documentation and training resources – text, media – into an overarching knowledge model </li></ul><ul><li>The knowledge model is created and maintained separate from the actual content – like creating a global index </li></ul><ul><li>“ Allows us to provide access to the information based on the model of the knowledge it contains” Steve Newcombe </li></ul><ul><li>Simple level: Organization of content by hierarchy, relationships </li></ul><ul><li>Next level: Organization of subjects , and relating content to those subjects </li></ul>
    13. 13. What is an Ontology? <ul><li>Terms used to describe and represent an area of knowledge – subject matter </li></ul><ul><ul><li>Model for the meaning of those terms </li></ul></ul><ul><ul><li>Vocabulary and the meaning of that vocabulary </li></ul></ul><ul><li>For us, that means standardized index, glossary, conditional tags/conditional attribute values </li></ul><ul><li>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 </li></ul>- Dr. Leo Obrst, MITRE Information Semantics Group
    14. 14. Introducing: Topic Maps <ul><li>Semantic knowledge model to express an ontology </li></ul><ul><li>ISO standard; can also be expressed as XML </li></ul><ul><li>Topic </li></ul><ul><ul><li>Represents a subject or concept </li></ul></ul><ul><ul><li>Categorized by Type </li></ul></ul><ul><li>Map </li></ul><ul><ul><li>Associations: relationships between topics </li></ul></ul><ul><ul><li>Occurrences: link between information resources and the subjects that they express something about </li></ul></ul>
    15. 15. Information Model Based on Topic Maps “ Subject Classification with DITA and SKOS,” Hennum, Anderson and Bird, October 2005
    16. 16. How can Topic Maps Help? <ul><li>Standardize subject matter, index and glossary </li></ul><ul><li>Determine valid usage of metadata and applicability / effectivity values (DITA conditional attributes) </li></ul><ul><li>Associative topic navigation, not just hierarchical </li></ul><ul><li>Results in better planning and content reuse while authoring; robust filtering and navigation in our deliverables </li></ul>
    17. 17. Modular Documentation <ul><li>Who is this Guy </li></ul><ul><li>Challenges for TechDoc Groups </li></ul><ul><li>Information Architecture </li></ul><ul><li>Revising Processes </li></ul>
    18. 18. Traditional Method for Developing Content <ul><li>Deliverable-based: </li></ul><ul><ul><li>Determine deliverables needed for product </li></ul></ul><ul><ul><li>Create an outline of topics needed </li></ul></ul><ul><ul><li>Locate and reuse existing content; write everything else from scratch </li></ul></ul><ul><li>Using topic-oriented architecture: </li></ul><ul><ul><li>Create outline using map </li></ul></ul><ul><ul><li>Link to existing topics; create space-holder topics for new content </li></ul></ul><ul><li>Maintain Master Topic List </li></ul>
    19. 19. Alternative Method using Information Architecture <ul><li>Solution Oriented Topic Architecture </li></ul><ul><li>Create a knowledge model of subjects encompassing: </li></ul><ul><ul><li>All products, features, system components </li></ul></ul><ul><ul><li>All product life-cycle stages </li></ul></ul><ul><li>From that model, compile lists of content to be created to express the knowledge model </li></ul><ul><li>Compile content to form maps representing documentation deliverables </li></ul><ul><ul><li>DITA Maps </li></ul></ul><ul><ul><li>SCORM Manifests </li></ul></ul>
    20. 20. Define Subjects and Types Example <ul><li>List Products and Solutions your company offers </li></ul><ul><li>For each Product: </li></ul><ul><ul><li>List System Components </li></ul></ul><ul><ul><li>List Features </li></ul></ul><ul><ul><li>List Tasks </li></ul></ul><ul><ul><li>List Life Cycle Stages </li></ul></ul><ul><li>For each Task: </li></ul><ul><ul><li>List Interfaces and Screens </li></ul></ul><ul><ul><li>User Roles </li></ul></ul>
    21. 21. Define Relationship Types <ul><li>Define relationships between subjects </li></ul><ul><ul><li>Product  System Component </li></ul></ul><ul><ul><li>Product  Platform Supported </li></ul></ul><ul><ul><li>Product  Feature </li></ul></ul><ul><ul><li>Feature  Task </li></ul></ul><ul><ul><li>Task  Interface </li></ul></ul><ul><ul><li>Task  Life Cycle </li></ul></ul><ul><ul><li>Task  User Role </li></ul></ul><ul><ul><li>System Component  Assembly </li></ul></ul>
    22. 22. List Relationships <ul><li>For each Product: </li></ul><ul><ul><li>Associate with Platforms Supported </li></ul></ul><ul><ul><li>Associate with Features </li></ul></ul><ul><li>For each Feature: </li></ul><ul><ul><li>Associate with Platforms Supported </li></ul></ul><ul><ul><li>Associate with Tasks </li></ul></ul><ul><li>For each Task: </li></ul><ul><ul><li>Associate with Interfaces and Screens </li></ul></ul><ul><ul><li>Associate with Life Cycle Stage </li></ul></ul><ul><ul><li>Associate with User Roles </li></ul></ul>
    23. 23. Define Subjects and Types <ul><li>Design Sell: Demos, Positioning, Related Products, Related Services, Implement: Initialize, Install, Configuration, Training Use: End Use, Administer Maintain: Troubleshoot, Optimize, Service, Maintenance </li></ul>Life Cycle Stages <ul><li>Servers: S1, S2, S3 Endpoints: E1, E2, E3 Peripherals: P1, P2, P3 </li></ul>Products Other Types : Features, Tasks, Interfaces, Screens, Use Cases, User Roles, Legal <ul><li>Assy1, Assy2, Assy3 </li></ul><ul><li>P101, P102, P103 </li></ul>Assemblies Parts <ul><li>Windows, Unix, Linux, Macintosh </li></ul>Platforms Subjects Type
    24. 24. Determine Content Resources <ul><li>Different types of content resources are used to express information about the subjects </li></ul><ul><ul><li>Procedure / Task </li></ul></ul><ul><ul><li>Concept / Description </li></ul></ul><ul><ul><li>Reference </li></ul></ul><ul><ul><li>Illustration </li></ul></ul><ul><ul><li>Drawing </li></ul></ul><ul><ul><li>Flash </li></ul></ul><ul><ul><li>Video </li></ul></ul><ul><ul><li>Presentation </li></ul></ul>
    25. 25. Generate List of Content to be Created <ul><li>Set rules: Content types needed to express each subject </li></ul><ul><li>Description, Supplier, Replacement Part, Diagram </li></ul>Part <ul><li>Installation Task, Maintenance Task, List of Parts </li></ul>Assembly <ul><li>List of buttons and fields (DITA Reference) </li></ul>Screen <ul><li>Description, Use Case </li></ul>Feature <ul><li>Procedure (DITA Task), safety instruction </li></ul>Task <ul><li>Overview (DITA Concept), Legal license / liability / warrantee </li></ul>Product Create Content Topic: For Each:
    26. 26. Author Content <ul><li>For each content instance, author knows the topic to be described and the characteristics via associations </li></ul><ul><li>Example: Procedure: Configuring Server Ports (DITA Task) </li></ul><ul><li>Characteristics / Associations: </li></ul><ul><ul><li>Product: Server S1 </li></ul></ul><ul><ul><li>User Roles: Administrator, Implementer </li></ul></ul><ul><ul><li>Interface: Admin </li></ul></ul><ul><ul><li>Screen: Port Configuration </li></ul></ul><ul><ul><li>Life Cycle Stage: Installation, Configuration </li></ul></ul><ul><ul><li>Platform: Windows, Unix </li></ul></ul><ul><li>Related Content: </li></ul><ul><ul><li>Screen element reference, Screen capture </li></ul></ul>
    27. 27. Generate Deliverables <ul><li>Set rules for each type of deliverable to create maps </li></ul><ul><li>Product Overview, Legal References </li></ul><ul><li>For each interface associated with Admin, Implementer, Technician </li></ul><ul><ul><li>For each screen, include screen reference </li></ul></ul><ul><li>For each Task associated with life cycle stage: Installation, Configuration, Administer, Troubleshoot </li></ul><ul><ul><li>Include Procedures (DITA Task) </li></ul></ul>Admin Guide <ul><li>Product Overview, Legal References, Installation and Configuration Procedures associated with User Role=Implementer </li></ul>Installation Guide Contents Deliverable
    28. 28. Generate Deliverables <ul><li>Set rules for each type of deliverable to create maps </li></ul><ul><li>Product Overview, Legal References </li></ul><ul><li>Getting Started </li></ul><ul><ul><li>For each Task associated with User Role: End User, Life Cycle: Installation, Configuration, include all procedures </li></ul></ul><ul><li>Features </li></ul><ul><ul><li>For each Feature </li></ul></ul><ul><ul><li>Include Feature Description </li></ul></ul><ul><ul><li>For each Task associated with Life Cycle: Use, User Role: End User include Procedure </li></ul></ul>User Guide Contents Deliverable
    29. 29. Conclusion <ul><li>Information Architecture focuses on subject matter separately from the content </li></ul><ul><li>First build your information model, then create your content topics to express that model ** All bases are covered! No more, no less </li></ul><ul><li>Collect content topics into any combination of deliverables you need </li></ul><ul><li>Deliverables can now be dynamically filtered, generated and navigated based on specific products, configurations, user roles, etc. </li></ul>
    30. 30. Be in touch <ul><li>Your feedback and ideas are appreciated! </li></ul><ul><li>Our team can help your organization evaluate and implement a solution suitable to your own requirements </li></ul>Joe Gelb [email_address] Tel: +972-993-8054