LavaCon 2017 - DITA: Start Small, Grow Big Using Open Source Tools

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

STILO | DITA: Start small, grow big using open source tools
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.

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

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

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!

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)

Manage - Git is distributed

Demo - Git
Tools & technologies:
► Git
► GitHub
► Desktop Git

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

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

Demo - Content introspection
► BaseX
► XQuery

Author
Hide the complexity
► tags and attributes
► link creation
► copy and paste
► content reuse
► full text search
► document context
► review comments
► track changes

Author
Make the experience:
► Guided
► Fluid
► Assisted

► 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

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 …

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

Demo - Authoring
► AuthorBridge
– guided
– fluid
► Assisted
– BaseX
– XQuery

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

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

Demo - Publish
► DITA OT
► Jekyll
► GitHub Pages

Manage - Git complexity
► So many branches..
This is GitFlow:

Manage - Git complexity
► So many possible workflows

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

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.”

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

Examples
► Wikipedia
► IBM Bluemix team
► DITA OT documentation

Demo - Wiki-like authoring
► AuthorBridge
► GitHub
► DITA-OT
► Jekyll
► GitHub Pages

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

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.

What's next
► Google Analytics
► Search
► Workflow
► Translation management

LavaCon 2017 - DITA: Start Small, Grow Big Using Open Source Tools

More Related Content

Similar to LavaCon 2017 - DITA: Start Small, Grow Big Using Open Source Tools (20)

More from Jack Molisani (20)

Recently uploaded (20)

LavaCon 2017 - DITA: Start Small, Grow Big Using Open Source Tools