Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

DITA Proof-of-Concept Publishing System


Published on

Final version of STC 2013 presentation. Describes the Intermec Tech Comm DITA Publishing System, created by a small staff on a small budget. Used to create product user manuals with DITA topic-based authoring.

Published in: Technology, Business
  • Hello! This presentation is intended for DITA beginners - writers who are thinking about, or have just started, DITA topic-based authoring. DITA 'pro users' won't hear anything new from me, but are welcome just the same!
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

DITA Proof-of-Concept Publishing System

  1. 1. 1COMPANY CONFIDENTIALDITA Proof-of-Concept Publishing SystemMatso Limtiaco, Principal Technical WriterIntermec Technologies CorporationEverett WA
  2. 2. 2COMPANY CONFIDENTIALWhat you will learn today How we built a DITA-based publishing process with a small staffand small (non-zero) budgetYou should already know… what DITA is the general concepts of “structured authoring”What you won’t learn from me today… Basic DITA authoring, except as part of the story Fancy DITA publishing tricks – our DITA implementation is simple Advantages of one software tool over others…we’re FrameMaker-centric here
  3. 3. 3COMPANY CONFIDENTIALA few words on DITA…“Darwin Information Typing Architecture” – an XML standard specific totechnical writing All content in concept, task, and reference topics Pieces of content within a topic are wrapped in structure tags (asopposed to semantic markup, like H1, Body, etc.) Every topic is standalone – needs no other topic to function as acomplete chunk of information No “go-to” software tool for DITA authoring Processes make some easy stuff hard Industry hasn’t embraced DITA as the future of writing “It isn’t easy, it’s efficient”
  4. 4. 4COMPANY CONFIDENTIALA few words on Intermec…Makers of supply-chain data collection hardware and software Bar code readers Mobile computers with bar code scanners, smartphone capability Bar code label printers and print media RFID readers and tags APIs and applicationsSeveral US locations, Singapore, field offices
  5. 5. 5COMPANY CONFIDENTIALA few words on Intermec Tech Comm…Small staff: Manager, 6 writers One junior writer with DITA background (in 2009)Mature processes and tools The usual deliverables… Template-based, task-oriented writing Tools: FrameMaker, InDesign, Robohelp Deliverables: Print, PDF, online Help
  6. 6. 6COMPANY CONFIDENTIALOur DITA Publishing System is a process for creatingproduct user manuals using DITA topic-basedauthoring.System uses existing tools Structured FrameMaker 8 Plug-ins – DITA-FMx, StructureSnippetsLimited output: PDF onlyLimited resources No DITA-specific staff – we have our “day jobs” too < $5000/year for training Software purchases every other year No CMS or IT support
  7. 7. 7COMPANY CONFIDENTIALManuals Published:2012: PC23 and PC43 Desktop Printer User Manual Manual del usuario de la impresora de escritorio PC23 y PC43 Bedienungsanleitung der Desktop-Drucker PC23 und PC43 PC23 和 PC43 桌面型打印机用户手册 Manual do Usuário das Impressoras de Mesa PC23 e PC43 PC23 和 PC43 桌上型印表機使用者手冊 PC23 및 PC43 데스크톱 프린터 사용 설명서 Руководство пользователя настольных принтеров PC23 и PC43 Manuel d’utilisation des imprimantes de bureau PC23 et PC43 Stampanti desktop PC23 e PC43 – Manuale dell’utente PM43 and PM43c Mid-Range Printer User Manual PM43-und PM43c-Mittelbereichsdrucker Bedienungsanleitung PM43 y PM43c impresora de nivel intermedio Manual del usuario PM43 et PM43c Imprimante de milieu de gamme Manuel d’utilisation PM43 e PM43c Stampante di fascia media Manuele dell’utente PM43 및 PM43c 중간 범위 프린터사용 설명서 PM43 e PM43c Impressora Média Manual do usuário PM43 и PM43c Принтер средних размеров Руководствопользователя PM43 和 PM43c 中端打印机用户手册 PM43 和 PM43c 中間範圍印表機使用手冊2012 (continued): PR2 and PR3 Mobile Receipt Printer User Manual PR2 和 PR3 移动收据打印机用户手册 PR2 和 PR3 行動收據印表機使用手冊 Manuel d’utilisation des imprimantes mobiles dereçus PR2 et PR3 Mobilbelegdrucker PR2 und PR3 –Bedienungsanleitung Manuale dell’utente delle stampanti portatili discontrini PR2 e PR3 PR2 및 PR3 모바일 영수증 프린터 사용 설명서 Manual do Usuário da Impressora Móvel de RecibosPR2 e PR3 Руководство пользователя мобильногопринтера для чеков PR2 и PR3 Manual de usuario de la impresora móvil pararecibos PR2 y PR3 CK3R and CK3X Mobile Computer User Manual 2nd revision, PC23 and PC43 Desktop Printer UserManual (all languages)2013 (Pending): Two more computer user manuals…
  8. 8. 8COMPANY CONFIDENTIALWhat does the publishing system cost?Item Date $Structured FM training, plus SFM DITA custom files 2009 4500DITA-FMx software 2009 1500Information Modeling workshop 2011 1400StructureSnippets software 2011 300TOTAL 2009 - present 7700
  9. 9. 9COMPANY CONFIDENTIALWhy did we decide to try DITA authoring?Mid-2009: Dept. wanted to learn more about DITA topic-basedauthoring – possibly create a proof-of-concept manual…Around the same time, Marketing announced a new line of bar codelabel printers… Printers would usecommon, proprietaryfirmware 10 languages requestedfor user manuals Product release date:Mid-2011
  10. 10. 10COMPANY CONFIDENTIALThe Perfect Proof-of-Concept?Good reasons for using DITA authoring: Shared firmware: Reusable content? Nine translations for user manuals: DITA topics can savetranslation costs Release date: 20+ months – Plenty of time to learn? Structured FrameMaker can handle DITA authoring – No needfor new tools?
  11. 11. 11COMPANY CONFIDENTIALBrief Timeline2010 Dept. moved into Structured FM2011 R & D of publishing methods, DITA authoring concepts Authoring of first manual built from DITA topics2012• Three manuals completed (July: First doc with multiple authors)• September: First revisions to original document2013• Two more manuals underway…
  12. 12. 12COMPANY CONFIDENTIAL2010: Moving to Structured FMConsultant provided one-day workshop, DITA structure applications Dept. goal: Learn the terminology and basic processes of structuredauthoringTwo writers attended minimalism classesAfter a year, most of department was familiar with structured authoringconcepts Two writers completed 150+ page user manuals in SFM Others: smaller documents, some single topics based on legacycontentPrinter schedule: 6 month slip – now due end of 2011…
  13. 13. 13COMPANY CONFIDENTIALSFM example…Element tags “off” Element tags “on”
  14. 14. 14COMPANY CONFIDENTIAL2011: Moving towards DITA authoring…When we started to write DITA topics, we discovered that SFM authoringisn’t exactly the same – we needed to learn more… How do you write a <shortdesc>? What kind of metadata do we want to include? What should we name our topic files? Where should we store topic files?Comtech workshop scheduled for mid-yearThe new Project Engineer… No more technical help? How to learn what this is supposed to do? Playing in the Sandbox:“How-to” procedures for publishing (but not authoring)
  15. 15. 15COMPANY CONFIDENTIALSandbox ExamplesPractice concept topic
  16. 16. 16COMPANY CONFIDENTIALSandbox ExamplesPractice task topic –tags turned off
  17. 17. 17COMPANY CONFIDENTIALSandbox ExamplesPractice reference topic
  18. 18. 18COMPANY CONFIDENTIALSandbox ExamplesPractice DITA map
  19. 19. 19COMPANY CONFIDENTIALSandbox Examples“Generate Book from Map…”
  20. 20. 20COMPANY CONFIDENTIALSandbox Examples“Generate Book from Map…”
  21. 21. 21COMPANY CONFIDENTIALMid-2011: DITA authoring begins…May: Information Modeling workshop Information Model: “A framework for categorizing and organizingcontent so it can be delivered and reused in a variety of ways” Starting point for authoring: Lists the base DITA elements you planto use and defines how to determine and organize content intoconcept, task, and reference topics
  22. 22. 22COMPANY CONFIDENTIALMid-2011: DITA authoring begins…May: Information Modeling workshop Information Model: “A framework for categorizing and organizingcontent so it can be delivered and reused in a variety of ways” Starting point for authoring: Lists the base DITA elements you planto use and defines how to determine and organize content intoconcept, task, and reference topicsWorkshop gives us a better idea of what to do with content… Principal writer begins work on Information Model “How-to” procedures become the “DITA Notebook” Between the Model and Notebook, our own best practices start toemerge…
  23. 23. 23COMPANY CONFIDENTIALExamples – Basic Authoring ConventionsFile naming conventions Concepts: “About…” or “How To…” Tasks: Action verbs – “Configure…,” “Install…,” “Connect…” References: Noun phrases – “Wi-Fi Settings,” “Printer Accessories” Maps: Keyed to product, doctype, chapter – “PC43UM_CH01”DITA Server organization Language Product type Product model number Concept, task, reference, graphics directories
  24. 24. 24COMPANY CONFIDENTIALDITA Server Structure: Relative to the map location, flatter is better…
  25. 25. 25COMPANY CONFIDENTIALSummer 2011: DITA authoring continues…Authoring new content was easier than expected Each feature generally needed one concept topic and multiple tasktopics, with reference topics as needed for “speeds and feeds” Information Model revised as we discovered more or fewer needsDocuments published to PDF for reviews Used existing review process (no difference to SMEs)Project Engineer: Continuous R & D (and authoring!) Trying to automate publishing tasks: language-specific templates,DITAVAL files to hide content More publishing procedures for the DITA Notebook
  26. 26. 26COMPANY CONFIDENTIALLate 2011: Translating the manuals…After English version approved, sent .zip of all topics to translationvendor Translated topics have English file names, xml:lang attribute Why not send complete manual to vendor? Page layout fees…Used EN bookmaps to generate FM files from translated topics FM files needed lots of page layout work
  27. 27. 27COMPANY CONFIDENTIAL2012: Using the system…March: Released the first manuals! Third writer started authoring topics, created a “best practices”authoring handbookJune: All three manuals done! “Noobs” did page layout work for vacationing writerJuly – Sept.: Started new computer user manual – first doc with multiple authors Revisions to first manual: three new topics, three revised topics
  28. 28. 28COMPANY CONFIDENTIALDid we really save money on translations?Full user manual Estimated: $6K/language (2009, includes DTP fees) Actual: <$5K/language (2011, no DTP fees)Revisions (nine languages) Estimated: $5K total Actual: $2KMost of the savings were (and will continue to be) in sustaining work…
  29. 29. 29COMPANY CONFIDENTIALHow about shared content?Printer manuals Shared content guesstimate: 30% of all topics Actual shared content: 20% of all topicsComputer manual Shared topics with new computer user manual:70% (with tags, @product as needed)…that’s 106 topics I don’t have to write!
  30. 30. 30COMPANY CONFIDENTIALThe Process1. Author topics in SFM.2. Create DITA maps. Each map = single chapter in finished book.3. Generate FM files (“build a book”) from the maps.4. Publish to PDF for reviews.5. Revise, publish, review again.6. Generate final FM files and perform final page edits.7. Publish to PDF, perform dept. QC.8. Send all topics (NOT completed EN book) for translation.9. Repeat 6-7 for each language.10. Release the manuals!… On to the examples!
  31. 31. 31COMPANY CONFIDENTIALConcept Topic with Element Tags …and without Element Tags
  32. 32. 32COMPANY CONFIDENTIALTask topic Reference topic
  33. 33. 33COMPANY CONFIDENTIALConcepts Tasks References
  34. 34. 34COMPANY CONFIDENTIALTypical DITA map Content of one map =one chapter in the book First topic in map is“chapter start” topic –used only for PDFpage layouts
  35. 35. 35COMPANY CONFIDENTIALTypical bookmap – a map of the chapter maps
  36. 36. 36COMPANY CONFIDENTIAL“Building the book”results in a set of SFMfiles corresponding toeach of the chaptermaps from the mainbookmap…
  37. 37. 37COMPANY CONFIDENTIAL“Raw” SFM files – no page layout tweaks yet…
  40. 40. 40COMPANY CONFIDENTIAL“Raw” SFM – H1 at top is supposedto be the “chapter start” page……so you have to manually assignthe correct page layout
  41. 41. 41COMPANY CONFIDENTIALChapter start page and orphansin the right places…
  42. 42. 42COMPANY CONFIDENTIALPlug-in Example: StructureSnippetsNote element inDITA source file
  43. 43. 43COMPANY CONFIDENTIALPlug-in Example: StructureSnippetsNote element inDITA source fileNote element ingenerated SFMAt book build time, SFM calls StructureSnippets to move all Note elementsinto a formatted table with graphic, like this:
  44. 44. 44COMPANY CONFIDENTIALIn our setup, SFM doesn’t recognizewhen a table column is too wide ornot wide enough… …so there’s a lot of table editing. Probably a way to make this happen automagically...
  45. 45. 45COMPANY CONFIDENTIALFixing columns in Russian?...Raw SFM Edited SFM
  46. 46. 46COMPANY CONFIDENTIALNon-DITA FM files – created in the standard way from existing templatesSFM files from DITAtopics & mapsThe Finished Book…
  47. 47. 47COMPANY CONFIDENTIALReusing bookmaps for translated docsDirectory structure is identical for all languages – we can use the samemaps for all versions of the document
  48. 48. 48COMPANY CONFIDENTIALManaging the Publishing SystemDITA implementations often result in new roles for team members: Information architect, Information developer, Information-development manager, Production manager(from CIDM Information Management News, 12/2005: The Effect of DITA onInformation-Development Roles)With a small team, we simplified the titles and share theresponsibilities…so we have: Project Manager Project Engineer
  49. 49. 49COMPANY CONFIDENTIALProject Manager Creates and maintains the Information Model Trains all writers in DITA authoring Sets project deadlines Makes recommendations to Dept. ManagerProject Engineer Creates and maintains the DITA Notebook Maintains and distributes the “engine files”: structure applications,“snippet” files, language-specific templates No XSL coding (yet…)
  50. 50. 50COMPANY CONFIDENTIALInformation Model Examples
  51. 51. 51COMPANY CONFIDENTIALInformation Model Examples
  52. 52. 52COMPANY CONFIDENTIALDITA Notebook Examples
  53. 53. 53COMPANY CONFIDENTIALDITA Notebook Examples
  54. 54. 54COMPANY CONFIDENTIALconcept, conbody fig, imagetask, taskbody inforeference, refbody noteshortdesc menucascade, uicontroltitle contextp, section userinputtable steps, step, cmdul, ol, li Metadata: @product, @platform Use to exclude stuff from the output (per Dave Gash)How much DITA do you need to know? DITA Specification defines 170+ elements…but we mostly use just these:
  55. 55. 55COMPANY CONFIDENTIALWhere we’re going next… More content reusability (conrefs) More output types (HTML prototype) Maybe new tools (oXygen? CCMS?)…but budget remains (non-zero) small… Only a few new manuals on the 6-9 month horizon, so a great timefor more R & D…
  56. 56. 56COMPANY CONFIDENTIALHints from the Project Engineer… No spaces in filenames Write everything down! Keep your pilot project simple IMO, publishing is the tricky part Why not DITA-OT? Allow plenty of time for page layout tasks (no DITA chops required) DITA authoring is easier than you think… Socio-political implications? Authors unwilling to embrace change? Use DITA if it helps you create stuff your customers want!
  57. 57. 57COMPANY CONFIDENTIALQuestions?My contact info:Matso…Thanks for attending!