DITA on a Shoe String
Download as PPT, PDF0 likes520 views
The document outlines the benefits of using DITA (Darwin Information Typing Architecture) for documentation practices, detailing pilot project costs and required tools for implementation. It highlights DITA's features, including lightweight options that allow for easier authoring without deep XML knowledge, and provides insights into various supporting technologies. Additionally, it discusses content analysis tools, collaborative environments, and the integration of build automation and source code control systems.
DITA on a Shoe String
- 1. DITA on a Shoe String April 20161 Stan Doherty, Ph.D. (Stan.Doherty@SimpliVity.com) Deborah Femia (Deborah.Femia@SimpliVity.com)
- 2. About the presenters . . . 2 Stan Doherty • SimpliVity: - Information Engineering Manager (1 yr) - Last-resort technical writer • OASIS - DITA Technical Committee (12 yrs) - DITA Help Subcommittee (7 yrs) - DITA Adoption Committee (2 yrs) Deborah Femia • SimpliVity: - Publications Infrastructure Engineer (.5 yr) - API Documentation Architect (.5 yr) • Technical writer, online Help dev. (18 yrs)
- 3. Here's the pitch . . . 3 Whether you are . . . - expanding your current investment in DITA - considering a migration to DITA - actively migrating to DITA - seeking ammunition to justify your staying out of DITA forever . . . the bar to developing pilots, prototypes, or proofs of concept is pretty low. Use Case #1 – 30-60-day pilot per participant = $0 cost (software) Use Case #2 – 60-180-day pilot per participant = $129 Use Case #3 – +180-day pilot per participant = $665
- 4. DITA information architecture . . . bare bones 4 Root DITA map Child DITA map Concept topic Task topic XML elements
- 5. DITA features and tools . . . where do I really need? 5 DITA features DITA-Related technologies 01. DITA-compliant editor 02. DITA Open Toolkit 03. XQuery editor 04. DITA-compliant CCMS 05. Schematron 06. Scalable Vector Graphics 07. Lightweight DITA (Markdown) 08. DITA4Publishers 09. Mind mapping editor 10. Wireframe editor 11. Spreadsheet 01. Inheritance (XML, processors) 02. Generalization (XML, processors) 03. Modular authoring (topic, maps) 04. Information typing (topic types, domains) 05. Content reuse (polymorphism) 06. Semantic markup (OOTB, customized) 07. Metadata: controlled values for attributes 08. Metadata: taxonomies 09. Metadata: classifications, ontologies 10. Extensibility (info types, domains) 11. Key-based referencing 12. Unicode and localization support 13. Content filtering (conditional assembly) 14. Content flagging (conditional styling) 15. Content/style isolation 16. Topic encapsulation 17. Content management integration
- 6. What components do you need to get started? 6 Authoring/translation tools Infrastructure/build tools 05. Stand-alone DITA Open Toolkit 06. Source code control environments 07. Build automation tools 08. Output styling tools (PDF, HTML) 09. Content analysis tools 01. DITA-compliant editor 02. Lightweight DITA editors (Markdown) 03. Integrated DITA Open Tookit 04. DITA book library (initial best practices)
- 7. What components do you need to get started? 7 Authoring/translation tools Infrastructure/build tools 05. Stand-alone DITA Open Toolkit > DITA-OT 06. Source code control environments > SVN > Git / Bitbucket 07. Build automation tools > Linux Shell script with cron job > Jenkins 08. Output styling tools (PDF, HTML) > Jarno Elovirta’s PDF Plugin Generator > Leigh White’s DITA for Print > Oxygen WebHelp Skin Builder 09. Content analysis tools > XQuery > Metrics reports 01. DITA-compliant editor > Syncrosoft Oxygen Author > JustSystems XMetaL Editor > Adobe Framemaker (DITA) 02. Lightweight DITA editors (Markdown) > MarkdownPad (Windows) > MacDown (Mac) > MdCharm (Linux) 03. Integrated DITA Open Tookit > Integrated with DITA editors 04. DITA book library (initial best practices) > Hackos, Introduction to DITA > Bellamy, DITA Best Practices > Self, DITA Style Guide > Kimber, DITA for Practitioners > White, DITA for Print
- 8. DITA-Compliant XML Editors 8 Critical features/benefits • Intelligent XML editing with content completion • Integrated DITA element and attribute reference • DITA validation and error checking • Visual conditionalization and profiling • Integrated publishing capabilities • Extensible and customizable • Robust user assistance available • Desktop client support (Windows? Mac? Linux?) Options and costs • Oxygen XML Author (www.oxygenxml.com) • 30-day free trial • $549 per license • JustSystems XMetaL Author (www.xmetal.com) • Free trial • Contact Sales for pricing. • Adobe Framemaker (DITA) • 30-day free trial • $29.99 per month per license or • $999 per license
- 9. DITA-Compliant XML Editors 9 Critical features/benefits • Intelligent XML editing with content completion • Integrated DITA element and attribute reference • DITA validation and error checking • Visual conditionalization and profiling • Integrated publishing capabilities • Extensible and customizable • Robust user assistance available • Desktop client support (Windows? Mac? Linux?) Options and costs • Oxygen XML Author (www.oxygenxml.com) • 30-day free trial • $549 per license • JustSystems XMetaL Author (www.xmetal.com) • Free trial • $XXX per license • Adobe Framemaker (DITA) • 30-day free trial • $29.99 per month per license or • $999 per license
- 10. Integrated DITA Open Toolkit 10 Critical features/benefits • Output transformation types supported by the stand-alone DITA Open Toolkit are available from within your DITA editor. > PDF, HTML5, HTMLHelp, RTF, TOCJS • All configuration options are visible from within your DITA editor. • Multiple versions of the DITA Open Toolkit can be used from within your DITA editor. Options and costs • Typically – NO COST – integrated with DITA editors
- 11. What is Lightweight DITA?? 11 Critical benefits • Author topics in a lightweight markup format – Markdown, HTML5, or MS Word. • Link to those lightweight topics directly from standard DITA maps. • Apply standard DITA metadata or filtering to the links calling lightweight topics. • Integrate both lightweight and standard topics in the same DITA maps. • Publish this content using any output transformation in the DITA Open Toolkit. Lightweight DITA is a variation of the OASIS DITA standard that is under active development. Unlike standard DITA 1.3, organizations using Lightweight DITA can do the following: • Learning XML is no longer a barrier to publishing through the DITA pipeline. • Technical publications groups do not need to be silo'd. • Anyone can contribute and collaborate. • The ROI for investing in DITA increases significantly.
- 12. What is Lightweight DITA?? 12 DITA 1.3 Map DITA 1.3 Map DITA 1.3 Map DITA SVT Map Tech Writers Engineers Mkt/Support WebMeisters C T RXML Editor c t rMarkdown Editor c t rMS Word c t rHTML5 Editor
- 13. What is Lightweight DITA?? 13 Critical benefits • Author topics in a lightweight markup format – Markdown, HTML5, or MS Word. • Link to those lightweight topics directly from standard DITA maps. • Apply standard DITA metadata or filtering to the links calling lightweight topics. • Integrate both lightweight and standard topics in the same DITA maps. • Publish this content using any output transformation in the DITA Open Toolkit. Lightweight DITA is a variation of the OASIS DITA standard that is under active development. Unlike standard DITA 1.3, organizations using Lightweight DITA can do the following: • Learning XML is no longer a barrier to publishing through the DITA pipeline. • Technical publications groups do not need to be silo'd. • Anyone can contribute and collaborate. • The ROI for investing in DITA increases significantly.
- 14. Source Code Control Environments 14 Critical features/benefits • Version control and snapshot archiving • Change tracking and logs • Branching and merging • Integration with issue tracking systems • Integration with build automation systems Options and costs • Your Development team’s source control system! – Free • Apache Subversion (SVN) • TortoiseSVN (Windows) – Free • Mac OS X SVN client – Included • Linux SVN client – Free • Cloud SVN provider – Fee per time period/user/feature • Many others • Git (command line) and optional GUI tool • Atlassian Bitbucket (a.k.a., Stash) – Cloud or on premises • Free for small teams, fee for large teams • TortoiseGit (Windows) – Free • SourceTree (Mac, Windows) – Free • Giggle (Linux) – Free • Many others
- 15. Build automation tools 15 Critical features/benefits • Scheduler for automated builds – nightly, when changes occur • Archiving of build artifacts • Integration with source control systems • Integration with issue tracking systems • Integration with your Development team’s software builds • Continuous integration (CI) build model Options and costs • Your Development team’s build automation system! – Free • Linux shell script with cron job – Included • Jenkins – Free • Many others To automate builds, use the stand-alone DITA Open Toolkit.
- 16. Output Styling Tools (PDF, HTML) 16 Critical features/benefits • Ability to add corporate branding and styles • Ability to customize every element of output style • Ability to define different styles for different output types Options and costs • Jarno Elovirta’s PDF Plugin Generator – Free • http://dita-generator.elovirta.com • Leigh White’s DITA for Print – ~$30 • Oxygen WebHelp Plugin – Included with Oxygen or $2094 standalone • Oxygen WebHelp Skin Builder – Free • https://www.oxygenxml.com/webhelp-skin-builder/
- 17. Content Analysis Tools 17 • Number of topics by language, domain (feature area), or topic type (concept, task, reference) • Number and IDs of topics called by more than one map (topic reuse) • IDs of topics containing one or more semantic elements/values, for example: <uicontrol>Federation</uicontrol> or <title>Create . . . </title> • Number and IDs of topics containing code block examples • And much more . . . Options and costs • Oxygen DITA Metrics Report – free with Oxygen • XQuery processors (BaseX) – free • String processing utilities – free > grep (Linux) > awk (Linux) > find (Windows) • Schematron – free Once your content is in XML topics (ASCII), you can analyze and profile your content quantitatively.
- 18. Content Analysis Tools 18 • Number of topics by language, domain (feature area), or topic type (concept, task, reference) • Number and IDs of topics called by more than one map (topic reuse) • IDs of topics containing one or more semantic elements/values, for example: <uicontrol>Federation</uicontrol> or <title>Create . . . </title> • Number and IDs of topics containing code block examples • And much more . . . Options and costs • Oxygen DITA Metrics Report – free with Oxygen • XQuery processors (BaseX) -- free • String processing utilities – free > grep (Linux) > awk (Linux) > find (Windows) • Schematron -- free Once your content is in XML topics (ASCII), you can analyze and profile your content quantitatively.
- 19. Content Analysis Tools 19 • Number of topics by language, domain (feature area), or topic type (concept, task, reference) • Number and IDs of topics called by more than one map (topic reuse) • IDs of topics containing one or more semantic elements/values, for example: <uicontrol>Federation</uicontrol> or <title>Create . . . </title> • Number and IDs of topics containing code block examples • And much more . . . Options and costs • Oxygen DITA Metrics Report – free with Oxygen • XQuery processors (BaseX) -- free • String processing utilities – free > grep (Linux) > awk (Linux) > find (Windows) • Schematron -- free Once your content is in XML topics (ASCII), you can analyze and profile your content quantitatively.
- 20. Content Analysis Tools 20 • Number of topics by language, domain (feature area), or topic type (concept, task, reference) • Number and IDs of topics called by more than one map (topic reuse) • IDs of topics containing one or more semantic elements/values, for example: <uicontrol>Federation</uicontrol> or <title>Create . . . </title> • Number and IDs of topics containing code block examples • And much more . . . Options and costs • Oxygen DITA Metrics Report – free with Oxygen • XQuery processors (BaseX) -- free • String processing utilities – free > grep (Linux) > awk (Linux) > find (Windows) • Schematron -- free Once your content is in XML topics (ASCII), you can analyze and profile your content quantitatively.
- 21. Content Analysis Tools 21 • Number of topics by language, domain (feature area), or topic type (concept, task, reference) • Number and IDs of topics called by more than one map (topic reuse) • IDs of topics containing one or more semantic elements/values, for example: <uicontrol>Federation</uicontrol> or <title>Create . . . </title> • Number and IDs of topics containing code block examples • And much more . . . Options and costs • Oxygen DITA Metrics Report – free with Oxygen • XQuery processors (BaseX) -- free • String processing utilities – free > grep (Linux) > awk (Linux) > find (Windows) • Schematron -- free Once your content is in XML topics (ASCII), you can analyze and profile your content quantitatively.
- 22. Recap . . . 22 Whether you are . . . - expanding your current investment in DITA - considering a migration to DITA - actively migrating to DITA - seeking ammunition to justify your staying out of DITA forever . . . the bar to developing pilots, prototypes, or proofs of concept is pretty low. Use Case #1 – 30-60-day pilot per participant = $0 cost (software) Use Case #2 – 60-180-day pilot per participant = $129 Use Case #3 – +180-day pilot per participant = $665
- 23. Useful Links . . . 23 Website URL DITA Open Toolkit http://www.dita-ot.org DITA Open Toolkit Installation Instructions http://www.dita-ot.org/2.2/getting-started/installing-client.html Java (JDK) Downloads http://www.oracle.com/technetwork/java/javase/download s/index.html Instructions for Adding the JDK to the Windows Path Variable http://docs.oracle.com/javase/8/docs/technotes/guides/install/windo ws_jdk_install.html#BABGDJFH BitBucket https://bitbucket.org/ TortoiseGit https://tortoisegit.org/ TortoiseSVN https://tortoisesvn.net/ Jenkins https://jenkins.io/index.html Git Plugin for Jenkins and Installation Instructions https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin https://wiki.jenkins-ci.org/display/JENKINS/Plugins#Plugins- Howtoinstallplugins Jarno Elovirta’s PDF Plugin Generator http://dita-generator.elovirta.com/#p1 Oxygen WebHelp Skin Builder https://www.oxygenxml.com/webhelp-skin-builder/