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
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/