Sawppy Documentation Suggestion: DITA

I outlined my Sawppy project and the challenges I want to tackle to the combined Write the Docs LA/SGVLUG meetup on the evening of October 8th. Sawppy’s current system of a loose set of Markdown files score highly on ease of contribution (challenge A) and ease of management (challenge B), but fall flat on querying dependencies (challenge C). What can I look into that helps improve information presentation without giving up the rest?

Fundamentally speaking, challenge C is not new, as it would be desirable in any large scale engineering project. The novel twist here is the desire to do it all with a system that is inviting for public contribution. As a general rule, documentarians for large engineering projects are professionals who have undergone training and have licenses for proprietary software tools.

DITA

Most such tools are excluded from consideration due to cost, but many of them deal with DITA, an open XML-based data model for authoring and publishing under the custody of the OASIS consortium. It is the standard answer to reassure customers wary of being locked in to proprietary file formats. And since it is an open format, there exists a DITA Open Toolkit to transform DITA data to desired output formats… HTML, PDF, even Markdown! There are learning resources at https://learningdita.com/

As a XML (and thus text) based format, DITA would be GitHub friendly for branching and merging. It is very flexible for creating any organization we want (creating a “Subject Schema” for DITA) but taking advantage of that power will take work. DITA Open Toolkit functions at a lower level relative to the other tools discussed later. A quick web search found many commercial offerings built on DITA (example: https://easydita.com/) but failed to find free open source counterpart.

So DITA is powerful, but that power comes at a cost, and I’ll have to decide if the cost/benefit analysis comes out in favor. This also applies to several other professional documentation concepts.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s