Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

DITA for Small Teams

1,365 views

Published on

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

Published in: Software

DITA for Small Teams

  1. 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. 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. 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. 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. 5. GENERAL TOOLS REQUIREMENTS 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 5
  6. 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. 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. 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. 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. 10. DITA FOR SMALL TEAMS APPROACH 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 15
  11. 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. 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. 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. 14. AUTHORING TOOLS 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 19
  15. 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. 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. 17. COLLABORATION MANAGEMENT TOOLS 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 22
  18. 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. 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. 20. PRODUCTION AUTOMATION 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 25
  21. 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. 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. 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. 24. LINK MANAGEMENT TOOLS 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 29
  25. 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. 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. 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. 28. TRANSLATION MANAGEMENT 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 33
  29. 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. 30. CHALLENGES 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 35
  31. 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. 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. 33. DFST REFERENCE CONFIGURATION 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 38
  34. 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. 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. 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. 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. 38. Demo 4/29/201 5 DITA For Small Teams | DITA NA 2015 | Contrext, LLC 43
  39. 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

×