Recommended
Recommended
More Related Content
Similar to DITA as Interchange Format for Crowdsourcing and Acquisitions
Similar to DITA as Interchange Format for Crowdsourcing and Acquisitions (20)
More from Ben Colborn
More from Ben Colborn (7)
Recently uploaded
Recently uploaded (20)
DITA as Interchange Format for Crowdsourcing and Acquisitions
- 1. DITA as Interchange Format for Crowdsourcing and Acquisitions Ben Colborn Director, Technical Publications Nutanix, San José Renée Haran, Manager, Learning Experience Design Nutanix, Durham
- 2. Nutanix Customer Journey Modernize IT with HCI Secureandautomateapplications,and consolidatestorage Build an Enterprise Cloud Multi-Cloud Services for Apps and Data Unifyoperationsacrosspublic and privateclouds Deliver enterpriseappsandVDI fromanysite
- 3. Nutanix Product Portfolio One Year Ago 4
- 5. Pros/Cons of Approaches DITA XML DTP markdown Low barrier to entry • • Topic-oriented • ~ Separation of content and format • • Comprehensible diff ~ • Comprehensive semantics • • Reuse capabilities • ~
- 7. YAML/Git Compatibility Word-to-DITA/ Sharepoint/Git Solutions/ Technical Marketing DITA/Git Product Documentation Salesforce Knowledge KB Articles Nutanix Support Portal Publishing Architecture
- 8. Word-to-DITA for Crowdsourcing Solving DITA issues of adoption and scale
- 9. In the beginning... • EDU 100% ILT model • 60-80% reuse of DITA topics • Shared repository • Mature publishing scheme • Only a few folks to manage ED U+ TP
- 10. Then there was Scale Hell • Shifted to eLearning + ILT • Rapid team expansion • Broke the DITA repo, mutiny • We also wanted to reuse Soln/TME content • How to repair? + :( TP
- 11. Use Cases Solutions/Technical Marketing 1. SMEs author documents in Word (template) 2. Editor finalizes content in Word 3. Production specialist publishes to support portal (DITA to HTML, PDF, ePUB) Technical Training/EDU 1. Trainers/SMEs author course material in Word (template) 2. Instructional designers finalize content in Word 3. Production specialist converts Word to DITA 4. Production specialist generates PDF and PPT from DITA source
- 14. Style-to-Tag Mapping for Education
- 17. markdown • Pros: Low barrier to entry; topic-oriented; separation of content and format; comprehensible diff • Cons: Comprehensive semantics; reuse capabilities • Untold number of markdown-based static site generators available for free or low cost • The obvious choice for a startup today • Used by multiple small companies that have been acquired by Nutanix
- 19. Publishing Process DITA D4P- HTML5 JSON Portal load markdown DITA D4P- HTML5 JSON Portal load markdown HTML JSON Portal load Mature markdown option 1 markdown option 2
- 20. Prerequisites • Create a DITAMAP that references the markdown files • Modify the markdown files to conform with DITA’s more constrained information model • Install DITA OT 3.x
- 22. Conclusion
- 23. Pros/Cons of Approaches DITA XML Word2DITA lwDITA Low barrier to entry ? ? Topic-oriented • ~ • Separation of content and format • • • Comprehensible diff • • Comprehensive semantics • ~ ~ Reuse capabilities • ~ •
- 24. Summary • LwDITA and W2DITA can be used as interchange formats for acquisitions and crowdsourcing (non-native DITA) • Companies with well-established DITA content practices can provide flexible interchange options for more-than-casual but less-than-professional authors • These "lightweight" options can be helpful in acquisitions and scenarios where reuse across business units/authoring groups that are otherwise siloed is needed
Editor's Notes
- These are really all facets of the same product
- DTP = Word, FrameMaker ~ = sort of, in some contexts Diff is the basis for reviews Semantics includes topic-level information typing Md is weak for complex procedures and tables Comprehensible diff is being able to run a diff between versions of topics Comprehensive semantics (markdown provides a basic topic structure, doesn't have "task topic" complex semantic components ,
- Important to go back to the "scale" and "providing a service" message
- DITA-4-Publishers Word to DITA plugin; Elliot Kimber
- Solutions/TM is in production today. Training is in POC but step 4 was in production with native-authored DITA source for several years.
- Looked at other options, even move to Markdown, which was viable but the team decided it was too disruptive to the team. Again, we are providing a service, and not adding too much additional complexity. (Lukas Lundell, product docs in Support Portal were so good, he wanted to leverage the publication process and then Renee wanted to leverage the content for reuse)
- Fixup is the chance to modify the result of the initial conversion. Kind of like XSLT but not fully recursive. Transformation breaks up a word doc styles (at heading level) into topics
- We can modify the style-to-tag mapping to address specific needs of the users; in this example we have added an Instructor Note for the trainers
- We're also able to take an extra step to create PPT slide decks for the trainers, this is basically a style sheet that looks at tge eleents in the DITA source, copies them into the PPT deck, and applies styling to them CMD is part of the step Codeblock is for command line code we want to show in the slide Here we give the codeblock a unique font style and font size
- 7-8 slides for each use case (30 total slides) Solves problem at Publication step, not authoring solution Benefits we can describe: using the publication mechanism for DITA, which is a barrier to adoption (complex, big, gorpy) allows us to leverage it in a different EDU: Story In the beginning there was DITA EDU and Tech Pubs were one team, First training manual ever produced was in DITA/Framemaker Close coupling teams... years.. Oxygen Education, failed Come full circle with this solution Solutions/Performance Education CCMS option (W2DITA, LW Open Toolkit 3, ditamap, reference the markdown files with attribute, stage in publication process
- Abstract: “flabby control and impoverished semantics” Would probably start with markdown if we were to start over, most acquisitions have been using markdown (Frame/Epoch) -challenges with onboarding -experimental/POC phase
- Pros and cons of two options? O1- have to manage the html transformation O2- have to manage the DITA transformation A>B, path of least resistence
- Some hierarchies may need to be adjusted with the ditamap: structures available in the SSGs not available in DITA and vice versa. Oxygen validates the markdown structure. Or, clean up the trashy structures that the SSGs devour
- You can use Word’s comparison tools which aren’t bad Allows you to use your DITA publishing pipeline, at cost of the upfront work Barrier to entry: Did we raise it? Author perspective? For W2DITA, there is no validation for the authors- has to be taken up by a FT writer/editor/instructional designer Goal: EDU is able to internally reuse topics developed for ILT in eLearning and also able to leverage content from Tech Pubc and Solutions/TMEs