You’re considering using DITA and would like to try it out without incurring significant upfront costs, but also keeping your options open longer-term. Where do you start? How will you approach the challenges of content creation, content management, and publishing your content? There are in fact plenty of options. The good news is that XML and DITA are open standards. This has led to a healthy ecosystem with quality commercial and inter-operable open source tools, that do away with vendor lock-in and keep operating costs down. We will discuss the three challenges, show an example of how end-to-end solutions can be built based upon Git and other open source tools. In fact, the result may be better than you’d expect.

1. Copyright © Stilo International plc
DITA:
Start small, grow big
using open source tools
Patrick Baker | VP Development & Professional Services
Stilo International
| LavaCon 2017
@StiloInt
#LavaCon

2. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Test drive DITA
► Get going with DITA quickly and with minimal investment of time and money.
► See if it is right for you before committing more heavily to the direction.
► Open standards has led to open source tools and a healthy community.

3. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage / Author / Publish
We need to address these fundamental aspects of the documentation lifecycle:
► Manage
– storing
– versioning
– released versions vs development versions
– validation and introspection
► Author
– content creation
– review
– validation and introspection
► Publish
– HTML, PDF output
– Search
– hosting
– deploying updates

4. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Your team
► tech writers
– plan, organize, and curate content
– pick tools, infrastructure, content
– identify requirements (e.g. content restrictions, publishing)
► content collaborators (SME)
– content authoring
– content review
► IT
– install and maintain tools
– scripting services

5. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Technology choices
There are many options before you. I have picked a path through.
► Manage - Git / GitHub, BaseX
► Author - AuthorBridge (built on CKEditor), BaseX
► Publish - DITA OT, GitHub Pages, Jekyll
Get ready for a mad dash!

6. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage - Git as the Repository
► history
– started by Linus Torvalds in 2005 when BitKeeper pulled their free version
► key feature
– distributed
► other goals
– high performance
– reliable
– scalable
– secure
– easy branching (creation & merging)

7. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage - Git is distributed

8. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Demo - Git
Tools & technologies:
► Git
► GitHub
► Desktop Git

9. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Git is scalable
► https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-
the-planet/
► Windows code base is approximately 3.5M files
► 300GB
► 4,000 engineers
► There are over 250,000 reachable Git commits in the history for this repo,
over the past 4 months.
► 8,421 pushes per day (on average)
► 2,500 pull requests, with 6,600 reviewers per work day (on average)
► 4,352 active topic branches

10. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage - Content introspection
XML can be queried just like any database can.
► Open standards: XPath, XQuery
► Very powerful author support
► XML Database: BaseX
– link validation
– full text search (reuse, related links)
– number of topics (of different types)
– broken images

11. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Demo - Content introspection
Tools & technologies:
► BaseX
► XQuery

12. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Author
Hide the complexity
► tags and attributes
► link creation
► copy and paste
► content reuse
► full text search
► document context
► review comments
► track changes

13. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Author
Make the experience:
► Guided
► Fluid
► Assisted

14. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
► User-friendly XML authoring tools try
to hide the complexity of XML and be
WYSIWYG
► But the structure keeps getting in the way!
Fluid Authoring
Wrestling with content structure…
… and winning

15. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Fluid Authoring
Depending on the tool, author is confronted with
content structure in different ways:
► Popups with element name choices
whenever user hits ENTER
► Attribute sidebar with esoteric contents
► Non-local changes to content when
inserting things
► Poor copy and paste support
Wrestling with content structure …

16. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Fluidity
Structure
MS Word
Typical XML Editor
But… this is
where we want
to be anyway!
Unfortunately,
there is an inverse
relationship between
fluidity and structure.
Wrestling with content structure …
Fluid Authoring

17. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Demo - Authoring
Tools & technologies:
► AuthorBridge
– guided
– fluid
► Assisted
– BaseX
– XQuery

18. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Publish
DITA Open Toolkit
► open-source publishing engine for DITA
► multi-channel publishing
Jekyll - Static website generator
► no database
► static doesn't mean not interactive, (JavaScript is fine)
► template language
GitHub Pages
► Free hosting solution
► GitHub Pages are powered by Jekyll

19. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Publish - DITA OT documentation process
► docs written in DITA (mostly)
► HTML generated with DITA OT & Jekyll
► HTML pushed to GitHub Pages
► Hosted via GitHub Pages

20. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Demo - Publish
Tools & technologies:
► DITA OT
► Jekyll
► GitHub Pages

21. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage - Git is distributed

22. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage - Git complexity
► So many branches..
This is GitFlow:

23. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Manage - Git complexity
► So many possible workflows

24. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Authoring - Invisible content management
content management is complex
► versions, branches, workflow, release management (not DITA specific)
Git is complex
► intended for developers, downside of distributed version control
For SME authors you have to make it invisible
► Leverage the Wiki model

25. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Wiki model
What's a wiki?
► A couple quotes from Ward Cunningham, the inventor of the Wiki.
“Wiki is a composition system; it's a discussion medium; it's a repository; it's a mail
system; it's a tool for collaboration.”
“The usefulness of Wiki is in the freedom, simplicity, and power it offers.”

26. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Wiki model
What do I mean by Wiki model?
The author works with the published view of content.
► familiar
► usually supports full text search
► includes navigation aids such as a table of contents
► author can edit topics by clicking a button
► Benefits
– Git branch management is made invisible
– content is findable (don't navigate CMS folder structures)
– document context, rather than topic editing

27. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Examples
► Wikipedia
► IBM Bluemix team
► DITA OT documentation

28. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Demo - Wiki-like authoring
Tools & technologies:
► AuthorBridge
► GitHub
► DITA-OT
► Jekyll
► GitHub Pages

29. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Summary – Keep it simple
► Authors
– SMEs don't know XML and DITA
– SMEs don't know Git, and complexities of version control
► Management
– Just enough
► Publishing
– static website (no database)
– simple hosting

30. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
Tools and technologies
I haven't talked about the virtues of DITA. I've taken them for granted. But they
are compelling. I've focused on how to get going with DITA.
► Manage - Git / GitHub, BaseX
► Author - AuthorBridge (built on CKEditor), BaseX
► Publish - DITA OT, GitHub Pages, Jekyll
Try DITA now. Invest later.

31. STILO | DITA: Start small, grow big using open source tools
Copyright © Stilo International plc
What's next
► Google Analytics
► Search
► Workflow
► Translation management