dita on a shoe string

DITA on a Shoe String

April 20161

Stan Doherty, Ph.D. ([email protected])

Deborah Femia ([email protected])

mailto:[email protected]

mailto:[email protected]

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)

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

DITA information architecture . . . bare bones

4

Root DITA map

Child DITA map

Concept topic

Task topic

XML elements

DITA features and tools . . . where do I really need?

5

DITA features DITA-Related technologies

01. DITA-compliant editor02. DITA Open Toolkit03. XQuery editor04. DITA-compliant CCMS05. Schematron06. Scalable Vector Graphics07. Lightweight DITA (Markdown)08. DITA4Publishers09. Mind mapping editor10. Wireframe editor11. 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 attributes08. Metadata: taxonomies09. Metadata: classifications, ontologies10. Extensibility (info types, domains)11. Key-based referencing12. Unicode and localization support13. Content filtering (conditional assembly)14. Content flagging (conditional styling)15. Content/style isolation16. Topic encapsulation 17. Content management integration

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)

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

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

http://www.oxygenxml.com/

http://www.xmetal.com/

DITA-Compliant XML Editors

9


• 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

http://www.oxygenxml.com/

http://www.xmetal.com/

Integrated DITA Open Toolkit

10


• 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

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 activedevelopment. 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

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

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 activedevelopment. 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.

Source Code Control Environments

14


• 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

Build automation tools

15


• 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.

Output Styling Tools (PDF, HTML)

16


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

http://dita-generator.elovirta.com/

https://www.oxygenxml.com/webhelp-skin-builder/

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 yourcontent quantitatively.


18


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



19


Options and costs




20


Options and costs




21


Options and costs



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

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/downloads/index.html

Instructions for Adding the JDK to the Windows Path Variable

http://docs.oracle.com/javase/8/docs/technotes/guides/install/windows_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+Pluginhttps://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/

dita on a shoe string

Software