The document discusses modular documentation and the importance of information architecture in technical writing. It emphasizes a shift from deliverable-based content to topic-oriented content that promotes reuse and efficiency. The piece also outlines best practices, challenges, and methodologies for creating a robust knowledge model to enhance documentation processes.

1. Modular Documentation Bringing the Pieces Together Joe Gelb Suite Solutions

2. Modular Documentation Who is this Guy Challenges for TechDoc Groups What Is Information Architecture? Revising Processes

3. Who is this guy? Background in Mechanical Engineering Production process planning CTO at Live Linx Built and managed the conversion team Responsible for design, development and implementation of tools Left Live Linx in 2006 to form independent consulting and implementation group Focus on DITA, international presence

4. Modular Documentation Who is this Guy Challenges for TechDoc Groups What Is Information Architecture? Revising Processes

5. Challenges of Documentation Groups Multi-purpose documents for multiple products, audiences, configurations, etc. Multi-channel publishing into many formats from the same source Reduce localization and desktop publishing costs Reuse content for multiple documents, across the organization and product lifecycle Provide more accessible, searchable, focused and updated content to internal and external customers

6. Modular Documentation Best practices for technical content development based on topic-oriented content architecture Topic-oriented content = modular = component-based documentation Instead of creating deliverables, we create discrete topics of information Standards being adopted: DITA, S1000D, SCORM

7. Topic-Based Content Using DITA Topics Each topic answers a single question Only enough information to understand one concept, perform one procedure or provide one set of reference information Maps Assemble topics into deliverables using Maps Define relationships between topics in relationship tables

8. Advantages of Using DITA More efficient authoring Reuse content in multiple deliverables Easier to maintain content Topic architecture and semantic tags promotes minimalization Easier to customize deliverables: multi-purpose Conditional attributes for product, platform, audience, and user defined conditions Multi-channel, single source, automated publishing

9. Challenges of Technical Writers Overall pressure to increase efficiency and reduce redundancy Topic-based content requires a paradigm shift from deliverable-based content Instead of managing deliverables, need to manage discrete topics – may be thousands Need better methodologies to plan, create, classify, manage, localize, publish, deliver and find content TWs are becoming information architects…

10. Modular Documentation Who is this Guy Challenges for TechDoc Groups Information Architecture Revising Processes

11. What is Information Architecture? The science (art?) of expressing a model or concept for information Used for activities that require expressions of complex systems Consists of: Structural design of shared information environments Method of organizing and labeling information From Wikipedia

12. What is IA for Documentation? Method for organizing documentation and training resources – text, media – into an overarching knowledge model The knowledge model is created and maintained separate from the actual content – like creating a global index “ Allows us to provide access to the information based on the model of the knowledge it contains” Steve Newcombe Simple level: Organization of content by hierarchy, relationships Next level: Organization of subjects , and relating content to those subjects

13. What is an Ontology? Terms used to describe and represent an area of knowledge – subject matter Model for the meaning of those terms Vocabulary and the meaning of that vocabulary For us, that means standardized index, glossary, conditional tags/conditional attribute values 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 - Dr. Leo Obrst, MITRE Information Semantics Group

14. Introducing: Topic Maps Semantic knowledge model to express an ontology ISO standard; can also be expressed as XML Topic Represents a subject or concept Categorized by Type Map Associations: relationships between topics Occurrences: link between information resources and the subjects that they express something about

15. Information Model Based on Topic Maps “ Subject Classification with DITA and SKOS,” Hennum, Anderson and Bird, October 2005

16. How can Topic Maps Help? Standardize subject matter, index and glossary Determine valid usage of metadata and applicability / effectivity values (DITA conditional attributes) Associative topic navigation, not just hierarchical Results in better planning and content reuse while authoring; robust filtering and navigation in our deliverables

17. Modular Documentation Who is this Guy Challenges for TechDoc Groups Information Architecture Revising Processes

18. Traditional Method for Developing Content Deliverable-based: Determine deliverables needed for product Create an outline of topics needed Locate and reuse existing content; write everything else from scratch Using topic-oriented architecture: Create outline using map Link to existing topics; create space-holder topics for new content Maintain Master Topic List

19. Alternative Method using Information Architecture Solution Oriented Topic Architecture Create a knowledge model of subjects encompassing: All products, features, system components All product life-cycle stages From that model, compile lists of content to be created to express the knowledge model Compile content to form maps representing documentation deliverables DITA Maps SCORM Manifests

20. Define Subjects and Types Example List Products and Solutions your company offers For each Product: List System Components List Features List Tasks List Life Cycle Stages For each Task: List Interfaces and Screens User Roles

21. Define Relationship Types Define relationships between subjects Product  System Component Product  Platform Supported Product  Feature Feature  Task Task  Interface Task  Life Cycle Task  User Role System Component  Assembly

22. List Relationships For each Product: Associate with Platforms Supported Associate with Features For each Feature: Associate with Platforms Supported Associate with Tasks For each Task: Associate with Interfaces and Screens Associate with Life Cycle Stage Associate with User Roles

23. Define Subjects and Types Design Sell: Demos, Positioning, Related Products, Related Services, Implement: Initialize, Install, Configuration, Training Use: End Use, Administer Maintain: Troubleshoot, Optimize, Service, Maintenance Life Cycle Stages Servers: S1, S2, S3 Endpoints: E1, E2, E3 Peripherals: P1, P2, P3 Products Other Types : Features, Tasks, Interfaces, Screens, Use Cases, User Roles, Legal Assy1, Assy2, Assy3 P101, P102, P103 Assemblies Parts Windows, Unix, Linux, Macintosh Platforms Subjects Type

24. Determine Content Resources Different types of content resources are used to express information about the subjects Procedure / Task Concept / Description Reference Illustration Drawing Flash Video Presentation

25. Generate List of Content to be Created Set rules: Content types needed to express each subject Description, Supplier, Replacement Part, Diagram Part Installation Task, Maintenance Task, List of Parts Assembly List of buttons and fields (DITA Reference) Screen Description, Use Case Feature Procedure (DITA Task), safety instruction Task Overview (DITA Concept), Legal license / liability / warrantee Product Create Content Topic: For Each:

26. Author Content For each content instance, author knows the topic to be described and the characteristics via associations Example: Procedure: Configuring Server Ports (DITA Task) Characteristics / Associations: Product: Server S1 User Roles: Administrator, Implementer Interface: Admin Screen: Port Configuration Life Cycle Stage: Installation, Configuration Platform: Windows, Unix Related Content: Screen element reference, Screen capture

27. Generate Deliverables Set rules for each type of deliverable to create maps Product Overview, Legal References For each interface associated with Admin, Implementer, Technician For each screen, include screen reference For each Task associated with life cycle stage: Installation, Configuration, Administer, Troubleshoot Include Procedures (DITA Task) Admin Guide Product Overview, Legal References, Installation and Configuration Procedures associated with User Role=Implementer Installation Guide Contents Deliverable

28. Generate Deliverables Set rules for each type of deliverable to create maps Product Overview, Legal References Getting Started For each Task associated with User Role: End User, Life Cycle: Installation, Configuration, include all procedures Features For each Feature Include Feature Description For each Task associated with Life Cycle: Use, User Role: End User include Procedure User Guide Contents Deliverable

29. Conclusion Information Architecture focuses on subject matter separately from the content First build your information model, then create your content topics to express that model ** All bases are covered! No more, no less Collect content topics into any combination of deliverables you need Deliverables can now be dynamically filtered, generated and navigated based on specific products, configurations, user roles, etc.

30. Be in touch Your feedback and ideas are appreciated! Our team can help your organization evaluate and implement a solution suitable to your own requirements Joe Gelb [email_address] Tel: +972-993-8054