DITA for Small Teams

DITA for Small Teams

Low cost solutions for DITA authoring, management, and production using

low-cost, high-value tools

4/29/201

5DITA For Small Teams | DITA NA 2015 | Contrext, LLC 1

Eliot KimberContrext, LLC

DITA North America 2015

About the Author

• Independent consultant focusing on DITA analysis, design, implementation, and training

• Doing SGML and XML for cough 30 years cough• Founding member of the DITA Technical Committee• Founding member of the XML Working Group• Co-editor of HyTime standard (ISO/IEC 10744)• Primary developer and founder of the DITA for

Publishers project• Author of DITA for Practitioners, Vol 1 (XML Press)• More DITA 1.3 accepted proposals than any other TC

member

4/29/201


Agenda

• What is DITA for Small Teams?• General tools requirements: What do you need?• DITA for Small Teams approach• Authoring tools• Collaboration management tools• Production management tools• Link management tools• Localization management tools• Demo

4/29/201


• Open-source project

• Overall goal: Make it quick and easy for small teams to get productive with DITA– Sample tool configurations and setup guidance

– Supporting code (Commit hooks and XQuery modules for link management)

• Project home: github/dita-for-small-teams

• Provide bridge to full-featured commercial CCMSes

4/29/201


DITA for Small Teams (DFST)

GENERAL TOOLS

REQUIREMENTS

4/29/201


"Doing DITA"

• Authoring support:– Something with which to write DITA XML documents

• Collaboration management:– Provide shared and managed access to document source files– Manage communication among team members

• Production management:– Automate the production and deployment of deliverables

• Reuse and link management:– Enable finding elements to reuse– Answer the "where used?" question for reused elements

• Localization management (if you translate)– Manage the localization workflow

4/29/201


Question of the Day:

Do I Need a CCMS?

• DITA authoring support requirements are non-trivial…

• …but commercial CCMS systems are expensive

• Small-team budgets are usually limited

– Can lower-cost tools meet requirements?

– Can you get started with DITA without first having a CCMS in place?

4/29/201


Answer: Maybe Not (Right Away)

• Possible to be productive without a CCMS

• Can get started with DITA without making CCMS investment up front

– Some teams may never have budget for CCMS, even if cost is justified

• CCMS often justified

– As data volume or author community grows

– To support localization processes

4/29/201


Challenge: What To Do?

• There are lots of things that could work

• What to choose?

• How to hook them up?

• None of it is hard, you just have to know what to do

• DITA for Small Teams project: – Provide a sample suite of tools and DITA-specific

configuration details

– Get teams started quickly

4/29/201


DITA FOR SMALL TEAMS

APPROACH

4/29/201


Low Cost, High Value

• Low cost:

– Open source where available

– Easy to provision and set up

– Good community support for users

• High value: Commercial where open-source simply not sufficient

4/29/201


Potential Tool Set

• Authoring: Whatever you choose• Source code control: git or equivalent• Collaboration communication: Jira, BitBucket, Trello,

Slack, etc.• Production automation:

– Continuous Integration: Jenkins, Travis CI, etc.– Open Toolkit or ditac

• Link management: XQuery database– eXist, BaseX, etc.– DITA-specific XQuery modules (DITA Community)

• Translation management: Commercial system (today)

4/29/201


DFST Model

4/29/201


Central git Repository

(Source controlVersioning)

Local gitRepository

XML AuthoringTool

Author's Workstation Shared Server

XQuery Database

(Search, link management)

Commit Hooks

Update linkDatabase

CI Server

Deliverables,Error checks,Etc.

Link Mgmt

Web AppWeb

Browser

Git Client

AUTHORING TOOLS

4/29/201


Free or Open-Source Authoring

Tools

• Various Eclipse plugins

– Search Eclipse marketplace

• Emacs XML mode

• Other standalone open-source editors

• Limited DITA-specific features

• May be challenging to configure for DITA use

4/29/201


Commercial Authoring Tools

• The usual suspects:– Arbortext Editor

– FrameMaker

– oXygenXML

– XMetal

• All are solid tools and a good value

• oXygenXML is the only cross-platform offering

• Commercial tool probably required for most authoring groups

4/29/201


COLLABORATION

MANAGEMENT TOOLS

4/29/201


Git or Better for Source Code

Control• True distributed version control• What all the cool kids are using• Well supported in free- or low-cost cloud

solutions– GitHub, BitBucket, etc.

• Good client support– SourceTree, Eclipse clients, TortoiseGit, Git Windows

client

• Good match to versioning needs for complex hyperdocuments– Branch-based visibility of specific versions

4/29/201


Jira, Trello, Etc.

• GitHub and BitBucket provide basic issue tracking and wikis

• Trello provides simple task management

• Many communication options

– Slack is flavor of the month

– Google hangouts, etc.

4/29/201


PRODUCTION AUTOMATION

4/29/201


Continuous Integration (CI)

• Integrates with your source code control repository

• Can react to new commits on specific branches– Rebuild deliverables whenever something changes

• Can run any process that can be automated with Ant or some other scripting language

• Can integrate the Open Toolkit or equivalent

• Will report success and failure

• Can maintain generated files for history

4/29/201


CI Tool Options

• Several open-source CI tools– Jenkins, Hudson, Travis CI, etc.

• Some have free or low-cost cloud offerings– Travis CI free for public GitHub repos, integrates

with GitHub nicely

– Bitnami

• Relatively easy to provision on your own server, whether a local machine or in the cloud (e.g., Amazon or Microsoft)

4/29/201


DITA Deliverable Generation

• DITA Open Toolkit

• Ditac

• Others?

• Ability to run on Linux probably a must

– Avoid Windows-only solutions unless you can provision Windows servers for automation

4/29/201


LINK MANAGEMENT TOOLS

4/29/201


XML Database As Search Server

• Use an XML database as read-only server

• Does not manage the source, only reflects current state

• Supports high-quality search

• Supports link management through DITA-specific function packages

• Integrates with source-code control system through commit hooks or CI system

4/29/201


XQuery Databases

• Two solid open-source XQuery databases:

– eXist

– BaseX

• MarkLogic is commercial but very high value

– May already have a license in your company

• All are easy to set up and use

4/29/201


DITA Link Management XQuery

Libraries

• https://github.com/dita-for-small-teams/dita-for-small-teams/modules

• Embodies knowledge of DITA linking and addressing

• Can answer where-used question

• Accessed through Web forms or authoring-tool integration

4/29/201


https://github.com/dita-for-small-teams/dita-for-small-teams/modules

TRANSLATION MANAGEMENT

4/29/201


Translation Management

• Only have commercial options at the moment

– E.g., XTM

• XTM has straightforward API

– Would be relatively easy to integrate using continuous integration or similar

• Strong localization requirements may motivate use of commercial CCMS

4/29/201


CHALLENGES

4/29/201


No Free Lunch

• Somebody has to set up the tools and keep things running

• Git-style version control can be a challenge– Different from systems like SVN, Perforce, etc.– Focus on branching takes getting used to– Have to be careful as you manage your source– Distributed nature requires good team

communication

• No central management UI• Individual users may have to set up more stuff

than usual

4/29/201


Requires Communication

• Team must communicate clearly and frequently

• Need clear conventions

• Need to document practice and process

4/29/201


DFST REFERENCE

CONFIGURATION

4/29/201


Many Options: Pick One

• Need a working sample of a DFST setup

• Tools chosen reflect biases or preferences of the DFST developers

• No particular magic to any of these choices

• Intended to demonstrate that this approach can work

4/29/201


Sample DFST Setup

• oXygenXML for authoring

• Git (through BitBucket) for source code control

• BitBucket for project management (issue tracker, wiki)

• Hosted Travis CI for production management using DITA Open Toolkit

• BaseX XML database for link management

• No localization support

4/29/201


Setting It Up

• Should be able to get something set up in less than a day

• Everything you need can be downloaded and installed pretty easily

• DFST GitHub project provides how-to instructions

– https://github.com/dita-for-small-teams

4/29/201


https://github.com/dita-for-small-teams

To Learn More

• More complete how-to guidance at DITA for Small Teams project on GitHub

• Landscape changes rapidly: Google search is your friend

• Your corporate IT group may already provide some or all of these tools

– Especially continuous integration and source code control

4/29/201


Demo

4/29/201


Resources

• DITA for Small Teams on GitHub: https://github.com/dita-community/dita-for-small-teams

• Git: git-scm.com

• Me: [email protected], http://contrext.com

4/29/201


https://github.com/dita-community/dita-for-small-teams

mailto:[email protected]

http://contrext.com

Software

DITA for Small Teams