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
17
DITA 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
17

• 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
17
DITA for Small Teams (D4ST)

GENERAL TOOLS
REQUIREMENTS
10/28/20
17

"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
17

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
17

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
17

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
17

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
17

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
17

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
17

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
17

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
17

DITA FOR SMALL TEAMS
APPROACH
10/28/20
17

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
17

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
17

DFST Model
10/28/20
17
Central git
Repository
(Source control
Versioning)
Local git
Repository
XML
Authoring
Tool
Author's Workstation Shared Server
XQuery
Database
(Search, link management)
Commit
Hooks
Update link
Database
CI Server
Deliverables,
Error checks,
Etc.
Link
Mgmt
Web App
Web
Browser
Git Client

AUTHORING TOOLS
10/28/20
17

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
17

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
17

COLLABORATION
MANAGEMENT TOOLS
10/28/20
17

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
17

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
17

PRODUCTION AUTOMATION
10/28/20
17

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
17

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
17

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
17

LINK MANAGEMENT TOOLS
10/28/20
17

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
17

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
17

TRANSLATION MANAGEMENT
10/28/20
17

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
17

CHALLENGES
10/28/20
17

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
17

Requires Communication
• Team must communicate clearly and
frequently
• Need clear conventions
• Need to document practice and process
10/28/20
17

DOCKER CONTAINERS TO
MANAGE SYSTEM COMPONENTS
10/28/20
17

“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
17

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
17

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
17

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
17

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
17

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
17

D4ST REFERENCE
CONFIGURATION
10/28/20
17

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
17

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
17

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
17

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
17

Resources
• DITA for Small Teams on GitHub:
https://github.com/d4st.org/dita-for-small-
teams
• Git: git-scm.com
• Me: ekimber@contrext.com,
http://contrext.com
10/28/20
17

DITA for Small Teams Workshop (Tekom 2017)

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (18)

Ähnlich wie DITA for Small Teams Workshop (Tekom 2017)

Ähnlich wie DITA for Small Teams Workshop (Tekom 2017) (20)

Mehr von Contrext Solutions

Mehr von Contrext Solutions (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

DITA for Small Teams Workshop (Tekom 2017)