DITA for Small Teams: Content Management on a Zero Budget

Content Management on Zero Budget:
DITA For Small Teams
The stone soup of content
management systems
12/4/201
7
DITA For Small Teams | DITA NA 2017 | Contrext 1
Eliot Kimber
Contrext, LLC
DITA North America 2017

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
12/4/201
7

Agenda
• What is DITA for Small Teams?
• Why is DITA for Small Teams
• What do I want?
• What have I actually built?
• Demo
12/4/201
7

12/4/201
7
All Tools Suck
Some suck less than others
—Eliot Kimber

WHAT IS DITA FOR SMALL
TEAMS?
12/4/201
7

• 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: dita-for-small-teams.org,
github.com/dita-for-small-teams
• Provide bridge to full-featured commercial
CCMSes
12/4/201
7
DITA for Small Teams (D4ST)

D4ST Model
12/4/201
7
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

12/4/201
7
How about something
more interesting?
Another system diagram?
Really?

WHY IS DITA FOR SMALL
TEAMS? SOME HISTORY…
12/4/201
7

1945
• Vannevar bush publishes his “As We May
Think” paper, the first formal description of
hypertext and inspires Douglas Englebart and
Ted Nelson
12/4/201
7

1980
• Ted Nelson publishes Literary Machines,
coining the term “hypertext” and outlining the
vision for the Xanadu system
12/4/201
7

1987 - IBM
• At local STC meeting watch video of Ted
Nelson, author of Literary Machines and
developer of Xanadu hypertext system,
talking about “hypertext”
• My young mind is blown and my life is
changed forever
12/4/201
7

1988(ish) - IBM
• I develop a technique for managing links
among 10 books in a library using flat files
and commented-out key definitions.
• Didn’t even have version control system
• But did have key-like indirect addressing in our
online delivery system (IBM BookManager)
12/4/201
7

1990-1992 - IBM
• Work with Don Day, Wayne Wohler, Simcha Gralla, and
others to develop SGML replacement for IBM
BookMaster
• Develop markup designs that would directly influence
DITA, including HyTime-based indirect linking and
formal markup extension
• Realized we would need content management
functionality to make large-scale authoring and
delivery practical
• ISO/IEC 10744 HyTime published. I become co-editor
of HyTime standard with Charles Goldfarb and Steve
Newcomb.
12/4/201
7

1994(ish) – Passage Systems
• See Xerox SGML content management system (original
base for current Astoria) for first time at trade show
• Asked simple question: if a paragraph with an ID is used in
two places, what happens?
– (Right answer is: everything works as it should)
– Answer I got: The ID occurs twice
• Realized it was a “document management system”
• What you need is a documents management system
• The Xerox guys had not understood the concept of SGML
entities.
• Meet Ted Nelson thanks to Yuri Rubinski
12/4/201
7

1996-1998 - ISOGEN
• Work on McDonnell Douglass/Boeing EMOD project –
ground-up SGML content management system for
aircraft manual authoring and publication
• Implement topicref-like use-by-reference mechanism
to manage re-use of components within large
maintenance manuals based on HyTime content
reference link idea
• My first (if not the first) practical implementation of
that idea
• Ken Holman brings Douglass Englebart to one of my
HyTime classes
• ISO/IEC 10744:1996 HyTime 2nd Edition published
12/4/201
7

1996-2000 - ISOGEN
• Support various clients with various commercial
content management systems
• They all fail in various ways
• One client had to stop our DTD enhancement
project because their CMS required an export and
reload to reconfigure the DTDs
• Another client’s system used a full-text engine
that could not handle periods in tag names (my
naming convention at the time for multi—word
element type names)
• Etc.
12/4/201
7

1998(ish) - ISOGEN
• Implement indirect link management system
using CVS and an in-memory relational database
(references to part numbers in maintenance
manuals)
• System performs for 10 years without
modification
• My greatest failure
• Boss had said “make sure it won’t scale or
perform”
• Oops
12/4/201
7

1999-2001 – DataChannel
• Implement Documentum-based bill drafting
system for State of Texas
• Discover that Documentum can’t actually do
SGML management
• Realize legislation reflects most challening
hyperdocument versioning use cases
• With John Heintz develop general model for
versioned hyperdocument management:
Snapshot-based Configuration Management
(SnapCM)
12/4/201
7

2001-2004 – DataChannel
• Implement quick-and-dirty CVS-based system
for managing DITA-like modular information
with lots of reuse for mobile phones as part of
larger authoring and print production project
• Stop-gap until the real system was in place “in 6
months”
• Three years later system was still in place and
being used for production work
• This system also included a key-like mechanism
for indirect references to images
12/4/201
7

2002-2005 - DataChannel
• With John Heintz, implement Python-based XML
content management using SnapCM model on
top of Zope object database
• Prove that model can perform and scale
• System never put into production use
• Code lost in IP tangle when DataChannel sells
ISOGEN to Innodata.
• Also realize that WebDAV is really missing the
Version part (it’s really WebDA) and that the
people thinking about versioning don’t really
understand the problems
12/4/201
7

2004 – Innodata Isogen
• Don Day invites me to be a founding member of
OASIS DITA Technical Committee
• Reflect on fact that all the content management
systems still suck
• ISOGEN sold to Innodata, forms Innodata Isogen
• In an airport start writing Java-based
implementation of SnapCM model, XIRUSS, using
forward engineering. Takes about 2 hours to
define API classes and methods.
12/4/201
7

2005 – Linux Project
• Linus Torvalds develops git for managing
linux project source code
• I do not become aware of git in any useful way
until almost 10 years later
12/4/201
7

2007– Really Strategies
• I go to work for Really Strategies (now RSI
Content Solutions), a vendor of a content
management system, because I need a bigger
paycheck.
• I Hope the RSuite CMS product is not a
steaming pile
• It’s not, or rather, they hadn’t made any
uncorrectable architectural decisions
12/4/201
7

2008 – 2013 – RSI Content
Solutions
• Help improve RSuite, including adding most of
the DITA functionality
• Develop DITA for Publishers project
• Fail to convince RSI to implement full
SnapCM model in Rsuite
• Contribute to development of keys feature in
DITA 1.2
12/4/201
7

2012 or 2013 - RSI Content
Solutions
• Starting to become that crank who just won’t
give up, I put up a SnapCM poster at Balisage
• Another attendee points out that the
SnapCM model is very similar to how git
works
• I find that very, very interesting
• DITA Europe: See SAP presentation on using
keys with Ixiasoft
– I’m very impressed
12/4/201
7

2013 - Contrext
• At DITA Europe have dinner with the head of a
non-CMS service provider in the DITA space
• We both complain about how none of the
content management systems really work but
we can’t say anything about it because we
need them.
• I decide I’m tired of pretending
12/4/201
7

2014 - Contrext
• I post to DITA Users my first expression of the
“DITA for small teams” idea
• Start DITA for Small Teams project on GitHub
• Realize that the one missing open-source
piece of the puzzle is a DITA-aware link
management system
• Start implementing the D4ST Link Manager
12/4/201
7

2015 - Contrext
• Balisage conference: present paper on the
D4ST approach
• Represents my third or fourth formal attempt
to get people to pay attention to SnapCM
model
• DITA North America: present talk on DITA for
Small Teams approach
• Learn about Docker and get very excited
because “this will simplify everything”
12/4/201
7

2016 - Contrext
• Get D4ST stuff kind of working
• Present D4ST course in Japan for InfoParse
– Hampered by fact classroom machines can only run 32-bit
Windows and thus no Docker
• Spend rest of year not working on D4ST, or much of
anything else for that matter
• Propose this talk as motivation to get back on D4ST
work
• Docker for Mac and Docker for Windows released.
Simplify things even further
• Jang Graat convinces me that D4ST needs to get done
and says he’s going to present on it in the spring
12/4/201
7

2017 - Contrext
• Make more progress on D4ST despite sudden
crushing workload
• Reflect on how most content management
systems still suck
• Present this talk to you
12/4/201
7

12/4/201
7
Talk about yourself much?
Get to the point

WHAT DO I WANT?
12/4/201
7

Happy and Productive DITA
Authors
• I want people who use DITA to be happy doing
it
• Using tools that enable full use of DITA’s
features
• That provide high value: lots of functionality
for the cost
12/4/201
7

More People Using DITA
• Make it easier to use DITA by reducing the
cost of entry
• Increase chance of initial project success
• Don’t spend entire project budget on a CMS
system that takes years to implement and
doesn’t work
12/4/201
7
That was your outside voice

Free Open-Source Solutions
• Lowest cost of entry is zero
• Enables quick evaluation of DITA
• Many teams are small with limited or no
budgets
• Technical documentation is usually a cost
center that gets no love
• That makes me sad
12/4/201
7

A Download-and-Use Solution
• Any solution needs to be “download and use”
as much as possible
• D4ST shows you can cobble together off-the-
shelf components and make it work
• But who has time for that?
12/4/201
7

To Demonstrate How to Do DITA
Link Management Correctly
• With the possible exception of Ixiasoft, no
commercial CMS system today does DITA link
management correctly
• More generally, all XML CMS systems are
fundamentally broken with respect to link
management
• This is my chance to show how it’s done
• Because this time they’ll listen to me!!!
12/4/201
7

WHAT DID I ACTUALLY MAKE?
12/4/201
7

D4ST Docker
• A set of pre-configured Docker containers with
all most of the parts you need:
– Shared git repository (GitLab)
– Link Manager (D4ST Link Manager)
– Authoring (oXygenXML Web Author)
– Production automation (DITA OT and GitLab CI)
– Web delivery (Caddy web server)
• Shell script to make setup and and operation
easier
12/4/201
7

What Is Docker?
• “Containerized software”
• Containers are light-weight virtual machines
• Each container intended to have one component
• Containers can be distributed through public
Docker Hub system
• Can quickly set up and deploy systems of related
containers
• Solves many deployment and configuration
management challenges
• Free open source base
12/4/201
7

Docker Support
• Docker for Windows
• Docker for macOS
• Docker server for linux
• Can run containers on:
– Personal machine
– Shared server or
– Cloud system (Azure, Amazon Web Services, etc.)
12/4/201
7

Docker Goodness
• Easy to deploy and maintain containers
• Easy to extend or modify or even replace
containers to meet local needs
• Networking among related containers easy
• Docker is gaining pretty deep traction in
industry
• Lots of tools provide Docker containers
12/4/201
7

Docker Annoyances
• Docker requires 64-bit Windows
– Docker for Windows requires Windows 10 Pro
– Docker Toolbox available for 64-bit Windows 8
• Technology is still pretty new
• Managing persistent volumes can be
challenging
• Managing licenses for licensed software
within containers can be a challenge
12/4/201
7

Demo
12/4/201
7

Work to Be Done
• Implement installers for macOS and Windows
• Complete link management functionality to
reflect DITA 1.3
• Implement better Link Manager UI
• Provide containers for other editors
• Improve performance of link manager
12/4/201
7

Questions?
12/4/201
7

Resources
• DITA for Small Teams: http://dita-for-small-teams.org
• DITA for Small Teams on GitHub: https://github.com/dita-
community/dita-for-small-teams,
• DITA for Small Teams Docker Solution: http://d4st.org
(coming soon)
• Git: http://git-scm.com
• Docker: http://docker.com
• Me: ekimber@contrext.com, http://contrext.com
• http://drmacros-xml-rants.blogspot.nl/2014/01/dita-
without-cms-tools-for-small-teams.html
• https://www.balisage.net/Proceedings/vol15/html/Kimber
01/BalisageVol15-Kimber01.html
12/4/201
7

DITA for Small Teams: Content Management on a Zero Budget

Recommended

Recommended

More Related Content

What's hot

What's hot (11)

Similar to DITA for Small Teams: Content Management on a Zero Budget

Similar to DITA for Small Teams: Content Management on a Zero Budget (20)

More from Contrext Solutions

More from Contrext Solutions (20)

Recently uploaded

Recently uploaded (20)

DITA for Small Teams: Content Management on a Zero Budget