Published on

Published in: Technology, News & Politics
1 Like
  • Be the first to comment

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

No notes for slide


  1. 1. Leveraging the DITA Community: Advice, Tools and Resources To Get Your Tech Pubs Team Up-To-Speed Bob Doyle [email_address] [email_address] 617-876-5676 Skype: bobdoyle DocTrain East, October 31, 2008
  2. 2. Who Am I? CEO, Editor, CMS Review related websites – CMS Wiki, CMS Forum, CMS News, CMS Calendar, CMS Glossary, CMSML, CMS Boston, Open Internet Lexicon, TaxoTips Founder, CM Professionals Contributing Editor, EContent Magazine Founder, DITA Users related websites – DITA Infocenter, DITA News, DITA Newsletter, DITA Wiki, and DITA Tutor DocTrain East, October 31, 2008
  3. 3. EContent Magazine <ul><li>Contributing Editor since 2004 </li></ul><ul><li>7 print columns per year </li></ul><ul><li>XML Authoring Tools Review </li></ul><ul><li>12 online columns per year </li></ul><ul><li>EC100 selection </li></ul><ul><li>Last column December 2008 </li></ul><ul><li>Information Philosopher </li></ul>DocTrain East, October 31, 2008
  4. 4. STC Intercom Magazine <ul><li>Content Management Systems Review </li></ul><ul><li>DITA Tools from A to Z </li></ul><ul><li>Download a copy from... </li></ul><ul><li> </li></ul>DocTrain East, October 31, 2008
  5. 5. Joined OASIS - 2006 <ul><li>Organization for the Advancement of Structured Information Standards </li></ul><ul><li>Member – DITA Technical Committee </li></ul><ul><li>Member – Learning and Content SC </li></ul><ul><li>Member – Help SC </li></ul><ul><li>Observer – Translation SC </li></ul><ul><li>Member – Editorial Board </li></ul><ul><li>Organizer – Boston DITA User Group </li></ul>DocTrain East, October 31, 2008
  6. 6. DITA Users – Launched in March 2007 <ul><li>DITA Users is an international membership organization </li></ul><ul><li>~750 members from 36 countries. </li></ul><ul><li>Members learn topic-based structured writing. </li></ul><ul><li>Author DITA with DITA Storm browser-based editor </li></ul><ul><li>Deliverables for web (XHTML), print (PDF), Help (Eclipse) from single-source documents. </li></ul><ul><li>Members have a personal workspace folder. </li></ul><ul><li>Finished work on web to show colleagues and clients. </li></ul><ul><li>Member directory has contact information. </li></ul><ul><li>Discounts on major DITA conferences, on tools (?), on </li></ul><ul><li>DITA tutorials and workshops, and on the DITA Report. </li></ul>DocTrain East, October 31, 2008
  7. 7. DITA Infocenter – Launched April 2007 <ul><li>DITA Infocenter is Eclipse-based Online Help </li></ul><ul><li>DITA Architectural Specification (1.0 and 1.1) </li></ul><ul><li>DITA Language Specification (1.0 and 1.1) </li></ul><ul><li>Open Toolkit User Guide (1.3.1) </li></ul><ul><li>Full-text search </li></ul><ul><li>Index of keywords </li></ul><ul><li>Table of contents </li></ul><ul><li>Generated from DITA files with Open Toolkit </li></ul>DocTrain East, October 31, 2008
  8. 8. DITA News – Launched June 2007 <ul><li>Aggregates blog posts from DITA bloggers. </li></ul><ul><li>Extensive listings of DITA tools from A to Z. </li></ul><ul><li>Events calendar with conference listings, </li></ul><ul><li>Websites, Publications, Webinars. </li></ul><ul><li>Glossary of DITA terms. </li></ul><ul><li>Content syndicated to other websites </li></ul><ul><li>Single-source publishing tools. </li></ul>DocTrain East, October 31, 2008
  9. 9. DITA Wiki – Launched July 2007 <ul><li>Resources with comments and discussions. </li></ul><ul><li>Mediawiki software (Wikipedia) </li></ul><ul><li>Architectural and Language specifications </li></ul><ul><li>Vendors and Products </li></ul><ul><li>Professional Services </li></ul><ul><li>Edited directly by the vendors </li></ul><ul><li>User comments </li></ul><ul><li>People section - major DITA players </li></ul><ul><li>Glossary of terms </li></ul>DocTrain East, October 31, 2008
  10. 10. DITA Newsletter – September 2007 <ul><li>Monthly summary of DITA news </li></ul><ul><li>Industry mailing list for press releases. </li></ul><ul><li>Next month’s events listings </li></ul><ul><li>Now on hold... </li></ul><ul><li>Looking for a new home </li></ul><ul><li>How many of you have read it? </li></ul>DocTrain East, October 31, 2008
  11. 11. DITA Tutor – Launched September <ul><li>Learning management system (Moodle LMS) </li></ul><ul><li>Self-paced online tutorials </li></ul><ul><li>Instructor-led online workshops </li></ul><ul><li>Powerpoint presentations </li></ul><ul><li>Some with audio recording </li></ul><ul><li>Recorded webinars </li></ul><ul><li>Courses in DITA techniques </li></ul><ul><li>Certificates of completion. </li></ul>DocTrain East, October 31, 2008
  12. 12. DITA Communities <ul><li>[email_address] </li></ul><ul><li> </li></ul><ul><li>OASIS </li></ul><ul><li>Contributions to OASIS </li></ul>DocTrain East, October 31, 2008
  13. 13. History of DITA <ul><li>Structured writing </li></ul><ul><li>Task-oriented Documentation </li></ul><ul><li>Minimalism </li></ul><ul><li>Single-source publishing > Reuse </li></ul><ul><li>Component Content Management </li></ul><ul><li>Topic-based authoring </li></ul><ul><li> </li></ul>DocTrain East, October 31, 2008
  14. 14. Structured Writing – 1960’s and 70’s <ul><li>Structured writing requires an analysis of content and a reorganization into the smallest possible coherent topics. Decades of research on such analysis and organization have been done by Information Mapping™ , who identified common document types, information types, and information blocks (chunks or topics) in use in education and commerce. </li></ul><ul><li>The reduction in structured authoring time may be offset by the increased time needed to analyze the content and break it into reusable chunks. There is no doubt that granular content, with well-defined purposes for each paragraph and sentence, is easier to author than linear content. But you may need skilled (i.e., more expensive) information developers to chunk your material. </li></ul>DocTrain East, October 31, 2008
  15. 15. Task-oriented Documentation – 1980’s <ul><li>Task-oriented docs have replaced system-oriented or product-oriented docs - the old comprehensive user manual. </li></ul><ul><li>ROI - The number of calls per month to the help desk on a product will almost certainly change when product documentation is task oriented and minimalist. And task-oriented content can feed directly into help-desk scripts. </li></ul>DocTrain East, October 31, 2008
  16. 16. Minimalism – 1990’s <ul><li>Minimalism aims to provide just what the impatient user is looking for. Remember, the web surfer is always just one click away from going to your competition's website. Your job is to strip away unnecessary content and get to the point. You can measure the return by pre-testing and post-testing content that has been re-architected along minimalist principles. </li></ul><ul><li>Minimalism appears to promise reduced costs for the simple reason that there is so much less content in well-prepared minimalist material. But it takes talented people to write succinct, action-oriented procedures that get users to understand quickly what they need to know and successfully do it. And minimalist material is best when it is tested for effectiveness, adding to costs. </li></ul>DocTrain East, October 31, 2008
  17. 17. Single-source Publishing – 1990’s <ul><li>The original definition of single-source publishing was providing multiple output formats like Web, Print, and Online Help from the original documents. </li></ul><ul><li>When you have one source for each piece of content, you get the astonishing ability to change it in one place and have the change propagate everywhere. A product name change becomes much more manageable. Your business-critical marketing messages are standardized everywhere. Some call single source a &quot;single source of truth&quot; because you are assured that your customers are not getting mixed messages that can confuse them, reduce sales, and increase the need for tech support. </li></ul>DocTrain East, October 31, 2008
  18. 18. Single-source plus Reuse <ul><li>Reusable content has a single source, of course, but reuse generally refers to content originally developed for one context that can be reused in another. This requires content that is topic-based and written for reuse by avoiding explicit references to context. </li></ul><ul><li>The cost savings associated with reuse of content increase greatly when your content goes through a workflow with distinct review and approval stages, for example legal approval. Content that is reused generally can avoid all or most of the extra steps in the workflow that involve accuracy of content. You will still need design approval of the in-context appearance of the reused content. </li></ul>DocTrain East, October 31, 2008
  19. 19. Component Content Management <ul><li>The latest buzzword in CMS is &quot;component.&quot; Most web content management (WCMS) segment content at the web page. While this may be adequate for simple websites written by one or a few content contributors, it is not acceptable for websites whose pages act as portals to diverse kinds of interactive content. </li></ul><ul><li>Modern corporate pages pull content in from multiple sources. Each content block is filled with a content component managed independently of all the other blocks on the page. A component has its own versioning and scheduling, its own writers, reviewers, and approval process. </li></ul>DocTrain East, October 31, 2008
  20. 20. Topic-based authoring <ul><li>A topic is a unit of information with a title and some form of content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit. </li></ul><ul><li>A topic aims to be context-free, so it contains no links to other topics. </li></ul><ul><li>In DITA, the topic is the basic unit of authoring and of reuse. </li></ul><ul><li>A topic is a content component </li></ul>DocTrain East, October 31, 2008
  21. 21. Why Concept, Task, and Reference? <ul><li>Remember Macintosh doc guidelines? </li></ul><ul><li>Learning MacPaint, Using MacPaint, the MacPaint Reference. </li></ul><ul><li>Today’s O’Reilly Books – Learning PHP, Programming PHP, PHP – the Definitive Reference </li></ul><ul><li>Concept = What is it? </li></ul><ul><li>Task = How do I do…? </li></ul><ul><li>Reference = All the details. </li></ul>DocTrain East, October 31, 2008
  22. 22. What’s a DITA Map? <ul><li>The DITA Map provides context for your context-free topics – the content . </li></ul><ul><li>You can have many maps, each one arranging the topics for different requirements – a reference manual, a tutorial, a help desk. </li></ul><ul><li>The map is like a table of contents that rebuilds the book dynamically. </li></ul>DocTrain East, October 31, 2008
  23. 23. What’s the DITA Open Toolkit? <ul><li>The Open Toolkit is an open-source end-to-end single-source publishing system. </li></ul><ul><li>It takes your topics and your maps and generates multiple output format deliverables, like print (PDF), web (HTML), and Help. </li></ul><ul><li>It is free and has been integrated into leading DITA editing and CMS tools. </li></ul>DocTrain East, October 31, 2008
  24. 24. Why Simplified XML? <ul><li>DITA is XML. </li></ul><ul><li>XML is way harder than HTML and most writers want no part of HTML. </li></ul><ul><li>So how can DITA be easier than XML? </li></ul><ul><li>Because XML separates content from presentation </li></ul><ul><li>And it also separates content from structure </li></ul>DocTrain East, October 31, 2008
  25. 25. What Is Content Anyway? <ul><li>It’s not the Presentation or the Structure! </li></ul><ul><li>Separate Presentation Layer from Content </li></ul><ul><li>Structure the Content </li></ul><ul><li>Tag Content with Meaning (semantics) by Metadata </li></ul>DocTrain East, October 31, 2008
  26. 26. Three Kinds of Markup <ul><li>The three layers use different “markup” </li></ul><ul><li>Style - <font>, <b>, <i> </li></ul><ul><li>Structure - <p>, <ol> </li></ul><ul><li>Semantics <name>, <price>, <product> </li></ul>DocTrain East, October 31, 2008
  27. 27. Three Kinds of XML <ul><li>The three layers use different technologies </li></ul><ul><li>XSLT Stylesheets (CSS) </li></ul><ul><li>XML Schemas (DTDs) </li></ul><ul><li>XML/DITA Documents </li></ul>DocTrain East, October 31, 2008
  28. 28. Three Different Professions <ul><li>The three layers are the work of different professionals </li></ul><ul><li>Designers for Style </li></ul><ul><li>Architects for Structure </li></ul><ul><li>Authors for Content and metadata </li></ul>DocTrain East, October 31, 2008
  29. 29. Simplified XML again <ul><li>The DITA Open Toolkit is XML with a starter set of stylesheets (XSLTs) and schemas (DTDs) so your organization does not have to invest in months or years of development </li></ul><ul><li>But simplified can be too simple… </li></ul>DocTrain East, October 31, 2008
  30. 30. DITA is not for writers alone.. <ul><li>Without style designers… (XSLTs) </li></ul><ul><li>Without structural architects… (DTDs) </li></ul><ul><li>DITA sucks! </li></ul><ul><li>It’s like publishing your annual report in Notepad text! </li></ul><ul><li>Although topics are components, they don’t have the metadata needed to assemble them intelligently. </li></ul>DocTrain East, October 31, 2008
  31. 31. So what’s the benefit for writers? <ul><li>Your work can feed into the dynamic assembly of complex information products </li></ul><ul><li>Websites, Help systems, Custom Print Documentation, Mobile snippets </li></ul><ul><li>You are an assembly line writer in the age of information automation! </li></ul><ul><li>Love it or hate it? </li></ul>DocTrain East, October 31, 2008
  32. 32. Topics are Content Components <ul><li>Even subtopic elements can be reusable components </li></ul><ul><li>Elements just need unique IDs </li></ul><ul><li>Then they can be conref ’d (content referenced) which means you can include them by reference in other topics. </li></ul><ul><li>Specialized topics have metadata created by the structure architects. </li></ul>DocTrain East, October 31, 2008
  33. 33. So what is specialization? <ul><li>You can specialize structures </li></ul><ul><li>You can specialize element names </li></ul><ul><li>Then valid topics can be written in DITA-compliant authoring tools without knowing anything about the underlying XML </li></ul><ul><li>And they can be assembled automatically using the metadata implicit in the specialization. </li></ul>DocTrain East, October 31, 2008
  34. 34. Three examples of specialization <ul><li>Concepts are specialized topics </li></ul><ul><li>Tasks are specialized topics </li></ul><ul><li>References are specialized topics </li></ul><ul><li>By understanding those specializations, you will know how specialization works </li></ul><ul><li>But remember that specialization is the work of document architects and information designers </li></ul>DocTrain East, October 31, 2008
  35. 35. A close look at a topic <ul><li>A topic has only three required elements. </li></ul><ul><li>an id attribute in the main topic tag (for reuse) </li></ul><ul><li>a title </li></ul><ul><li>a body </li></ul>DocTrain East, October 31, 2008
  36. 36. A close look at a topic… <ul><li>It can have dozens of optional elements, many of which are very familiar HTML elements, like paragraphs <p>, lists <ul>, and tables <table> </li></ul>DocTrain East, October 31, 2008
  37. 37. A close look at a topic… <ul><li>Elements are shown schematically as colored boxes in a hierarchy. </li></ul><ul><li>They are actually XML tag structures, properly nested and well formed. </li></ul><ul><li><topic id=&quot;1&quot;> </li></ul><ul><li><title>My Topic</title> </li></ul><ul><li><shortdesc>About my topic...</shortdesc> </li></ul><ul><li><body> </li></ul><ul><li><p>Some content</p> </li></ul><ul><li><p>Some more content</p> </li></ul><ul><li></body> </li></ul><ul><li></topic> </li></ul>DocTrain East, October 31, 2008
  38. 38. The Concept Type <ul><li>The concept type specializes topic element names and topic structure. </li></ul><ul><li>The root element is renamed concept and the body element is renamed conbody . </li></ul><ul><li>Any number of paragraphs , lists , tables , etc. may appear, but none of these are allowed after the first section or example . </li></ul><ul><li>Sections and examples can then appear in any order. </li></ul>DocTrain East, October 31, 2008
  39. 39. The Task Type <ul><li>The task type specializes topic element names and topic structure. </li></ul><ul><li>The root element is renamed task and the body element is renamed taskbody . </li></ul><ul><li>One task prerequisite and one context (both specializations of section ) are followed by steps (a specialization of ordered list ). </li></ul><ul><li>Each step must have a command , then optional info , a step example , choices , and a step result . </li></ul><ul><li>The set of steps is followed by the task result , examples , and any task postrequisite . </li></ul>DocTrain East, October 31, 2008
  40. 40. The Reference Type <ul><li>The task type specializes topic element names and topic structure. </li></ul><ul><li>The root element is renamed reference and the body element is renamed refbody . </li></ul><ul><li>The refbody includes a properties element (a specialization of simpletable ) a three-column table of property types, values, and descriptions. </li></ul><ul><li>The element refsyn (reference syntax) is a specialization of the section element. </li></ul>DocTrain East, October 31, 2008
  41. 41. A Five-Minute Tutorial <ul><li> </li></ul>DocTrain East, October 31, 2008
  42. 42. Thank you. <ul><li>Contact Bob Doyle </li></ul><ul><li>[email_address] </li></ul><ul><li>[email_address] </li></ul><ul><li>Read my articles </li></ul><ul><li> </li></ul><ul><li> </li></ul><ul><li>Please join DITA Users </li></ul><ul><li> </li></ul><ul><li>This presentation is online at: </li></ul><ul><li> </li></ul>DocTrain East, October 31, 2008
  43. 43. My background Ph.D. Astrophysics, Harvard, 1968 Collaborative Observing Program, NASA Skylab 1970-72 Super8 Sound, 1973-78 Merlin and 5 other computer games– 1977-81 iXO Telecomputer – 1980-87 MacPublisher – 1984-1987 Digital Video Editor, New Media Magazine -1993-1999 DocTrain East, October 31, 2008
  44. 44. Parker Brothers Games DocTrain East, October 31, 2008
  45. 45. iXO Telecomputer <ul><li>Computer-initiated dialogues (AI) </li></ul><ul><li>Yes, No, Help, Repeat keys </li></ul><ul><li>“ Operators are standing by” </li></ul><ul><li>Stock trades, airline reservations, bill paying. </li></ul><ul><li>Hearing-impaired </li></ul><ul><li>Powered from phone line </li></ul><ul><li>Venture capital $13 million </li></ul><ul><li>Never developed the backend database services </li></ul><ul><li>Huge NOL carry-forward </li></ul>DocTrain East, October 31, 2008
  46. 46. MacPublisher <ul><li>First Desktop Publishing Program </li></ul><ul><li>11 th Certified Mac Developer </li></ul><ul><li>Shipped in 1984 </li></ul><ul><li>Laserwriter in 1985 </li></ul><ul><li>First “spot color” text on Apple Imagewriter </li></ul><ul><li>First rotated text/gaphics </li></ul><ul><li>Sold 20,000 copies </li></ul><ul><li>MacIndexer </li></ul><ul><li>Mac-Hyphen </li></ul><ul><li>Sold to Letraset in 1987 </li></ul>DocTrain East, October 31, 2008
  47. 47. The First Podcast - 2003 <ul><li>Christopher Lydon (NPR’s “The Connection”) </li></ul><ul><li>Dave Winer </li></ul><ul><li>Adam Curry </li></ul><ul><li>Bloggercon </li></ul><ul><li> </li></ul><ul><li>Lydon’s “Open Source” Show </li></ul>DocTrain East, October 31, 2008
  48. 48. Brown Television (BTV) Doug Liman DocTrain East, October 31, 2008
  49. 49. Hi-8 Users Group Funded Videomaker Magazine, Hi-8 Group became Desktop Video Group in 1992 DocTrain East, October 31, 2008
  50. 50. HRTV and Quad Sound Harvard-Radcliffe Film Workshop was in the basement of Holmes Hall (North/Pforzheimer House) where the old Radcliffe Radio Station and Morse Music Library were located. In the mid-80’s it became HRTV and the radio broadcast booth and adjoining sound rooms became Quad Sound Studios. DocTrain East, October 31, 2008