Stan Doherty and Debbie Femia from SimpliVity Corporation on implementing DITA pilots with little budget.

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/