Low cost solutions for DITA authoring, management, and production using low-cost, high-value tools

1. DITA for Small Teams
Low cost solutions for DITA authoring,
management, and production using
low-cost, high-value tools
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 1
Eliot Kimber
Contrext, LLC
DITA North America 2015

2. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 2

3. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 3

4. • 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 4
DITA for Small Teams (DFST)

5. GENERAL TOOLS
REQUIREMENTS
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 5

6. "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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 6

7. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 12

8. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 13

9. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 14

10. DITA FOR SMALL TEAMS
APPROACH
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 15

11. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 16

12. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 17

13. DFST Model
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 18
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

14. AUTHORING TOOLS
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 19

15. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 20

16. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 21

17. COLLABORATION
MANAGEMENT TOOLS
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 22

18. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 23

19. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 24

20. PRODUCTION AUTOMATION
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 25

21. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 26

22. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 27

23. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 28

24. LINK MANAGEMENT TOOLS
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 29

25. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 30

26. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 31

27. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 32

28. TRANSLATION MANAGEMENT
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 33

29. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 34

30. CHALLENGES
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 35

31. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 36

32. Requires Communication
• Team must communicate clearly and
frequently
• Need clear conventions
• Need to document practice and process
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 37

33. DFST REFERENCE
CONFIGURATION
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 38

34. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 39

35. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 40

36. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 41

37. 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
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 42

38. Demo
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 43

39. Resources
• DITA for Small Teams on GitHub:
https://github.com/dita-community/dita-for-
small-teams
• Git: git-scm.com
• Me: ekimber@contrext.com,
http://contrext.com
4/29/201
5
DITA For Small Teams | DITA NA 2015 | Contrext, LLC 44