DITA for Small Teams Workshop (Tekom 2017)

DITA for Small Teams

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

low-cost, high-value tools

10/28/20

17DITA For Small Teams Workshop | Tekom 2017 1

DITA for Small Teams Workshop

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

10/28/20


• 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)– “Download and use” tool set

• Project home: http://www.d4st.org

• Provide bridge to full-featured commercial CCMSes

10/28/20


DITA for Small Teams (D4ST)

http://www.d4st.org/

GENERAL TOOLS

REQUIREMENTS

10/28/20


"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

10/28/20


Authoring Tools

• Must handle XML generally– Validation against grammars (DTDs, XSDs, RNGs)

– Visual editing ("tags off" mode)

• Understand DITA– Maps and topics

– DITA addressing (keys and key references)

– DITA-specific filtering

• Make local production convenient– E.g., run the Open Toolkit or equivalent

10/28/20


Collaboration Management

• Two aspects to collaboration management:– Source access control and versioning

– Team communication and work coordination

• For source control:– Need shared and managed access to source files (XML

and media)

– Need versioning of all assets

• For team communication:– Issue tracking and management

– Online communication (voice, IM, etc.)

10/28/20


Production Management

• Automate production of deliverables– React to updates to source files

– Enable timed or on-demand production

• Manage configuration details for different deliverables– Filtering and flagging

– Deliverable-specific parameters

• Provide appropriate status and logging to users and managers

10/28/20


Link Management

• DITA documents are hyperdocuments

• Two main challenges:– What content do I have so I can reuse it?

– What other documents use this specific element?

• Requires ability to search across all source efficiently

• Requires ability to get quick answer to the "where used?" question

• Requires understanding of DITA-specific linking

10/28/20


Localization Management

• Manage the translation process for documentation source

– Making source files available to translators

– Receiving translated files

– Managing translation memory

– Managing and reporting process status

• Details may be dictated by localization supplier

10/28/20


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?

10/28/20


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

10/28/20


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

10/28/20


DITA FOR SMALL TEAMS

APPROACH

10/28/20


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

10/28/20


Potential Tool Set

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

• Production automation:– Continuous Integration: GitLab, 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)

10/28/20


DFST Model

10/28/20


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

10/28/20


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

10/28/20


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

10/28/20


COLLABORATION

MANAGEMENT TOOLS

10/28/20


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, GitLab, 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

10/28/20


Jira, Trello, Etc.

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

10/28/20


PRODUCTION AUTOMATION

10/28/20


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

10/28/20


CI Tool Options

• Several open-source CI tools– GitLab, 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

– GitLab

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

10/28/20


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

• Docker containers can avoid local configuration problems

10/28/20


LINK MANAGEMENT TOOLS

10/28/20


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

10/28/20


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

10/28/20


TRANSLATION MANAGEMENT

10/28/20


Translation Management

• Only have commercial options at the moment– E.g., XTM, Fluenta

• XTM has straightforward API– Would be relatively easy to integrate using continuous

integration or similar

• Fluenta has strong DITA support– Import and export DITA to and from XLIFF and

translation memory

• Strong localization requirements may motivate use of commercial CCMS

10/28/20


CHALLENGES

10/28/20


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

10/28/20


Requires Communication

• Team must communicate clearly and frequently

• Need clear conventions

• Need to document practice and process

10/28/20


DOCKER CONTAINERS TO

MANAGE SYSTEM COMPONENTS

10/28/20


“Containers”

• Small virtual machines that run inside a larger “container manager”

• Two types of containers:– “Data volume” containers just hold data

– Regular containers run software

• Containers are run in a consistent environment

• Container management services assist with deployment and update

• Container managers available for most platforms

10/28/20


Docker Container System

• Open-source system for containers: docker.com

• Public container repository: Docker Hub

• Containers are layered– Containers can share layers

– Can make new containers by adding layers

• Layers make container storage very efficient

• Quick to download and update after first download

10/28/20


Use Containers to Build

Systems• Can hook containers together like Lego blocks

• Can quickly build system of related programs and data from containers

• Use Docker Compose to easily configure sets of containers

• Can start, stop, and update containers with one command

• Ideal for D4ST use case

10/28/20


Lots of Off-the-Shelf Containers

• Most popular tools available as containers:

– Web servers

– Version control systems

– Programming languages

– Linux distributions

• Can quickly build custom containers from standard containers

• No programming required

10/28/20


Docker Deployment

• Put containers on Docker Hub

• When you run a container, Docker downloads it automatically if not available locally

• Can pull updates to existing containers easily

• Can set up private Docker repository within enterprises if necessary

• Use Docker Compose to manage multiple containers as a unit

10/28/20


Docker is Cross Platform

• Same Docker containers can run on any platform

• Makes deployment and use easier

– Once Docker system is installed

• Can be used on single-user or multi-user server

• Avoids need to install and maintain multiple tools on each user’s machine

10/28/20


D4ST REFERENCE

CONFIGURATION

10/28/20


Many Options: Pick One

• Need a working sample of a D4ST setup

• Tools chosen reflect biases or preferences of the D4ST developers

• No particular magic to any of these choices

• Intended to demonstrate that this approach can work

10/28/20


Sample D4ST Setup

• oXygenXML for authoring

• Git (through GitLab) for source code control

• GitLab for project management (issue tracker, wiki)

• GitLab CI for automated production using DITA Open Toolkit

• BaseX XML database for link management

• Fluenta client for translation management (commercial tool)

• Use Docker for all components except oXygenXML, Fluenta, and git client

10/28/20


Setting It Up

• Install editor, translation manager, git client

• Install Docker

• Get D4ST client distribution

– Docker compose script

– Wrapper shell script for convenience

• Run “d4st up” command to start the Docker containers

• Start authoring

10/28/20


To Learn More

• More complete how-to guidance at DITA for Small Teams web site

• 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

10/28/20


Resources

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

• Git: git-scm.com

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

10/28/20


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

mailto:[email protected]

http://contrext.com

DITA for Small Teams Workshop (Tekom 2017)

Software

Transcript of DITA for Small Teams Workshop (Tekom 2017)