DITAWriter’s Lightweight DITA Code Samples

LwDITA Code Samples

I believe that one of the best ways people learn is to get “hands on” and play with things at the code level in order to get a real understanding as to how things are supposed to work. That’s the approach I took when devising a set of Lightweight DITA (LwDITA) code samples, which are freely available on GitHub.

Wanting to work with some real technical content, I found some open source/out-of-copyright content for a memory expansion module for the venerable TRS-80 (better known as the “Trash 80” for those of who were around when it was originally released). The core manual can be found on Project Gutenberg, with marketing copy and code sample additions coming from Archive.org. I’ve tried to keep the prose as-is in all of the code samples with the exception of the “full” DITA example, where fully typed topics required some (much needed) paring down and re-organizing of the original content. To be fair, this is a similar situation to any technical writer taking original, un-typed LwDITA content and then converting it to fully typed DITA 1.3 content.

Example code can be found for all flavours of LwDITA including:

This was a fun and useful exercise for me, and I hope that you get something out of this too. It was started when the current LwDITA Committee Note (which outlines the direction LwDITA will appear in the forthcoming 1.0 specification) was still in development. Along the way I discovered a couple of quirks which I reported to the LwDITA sub-committee, and these got fixed prior to the release of the final Committee Note. Definitely useful from that perspective too!

I make no claims that the code examples are 100% perfect, as errors are bound to have crept in while I putting these together. If you find any problems with the way the code samples are constructed, please report it as an “issue” and describe it in detail.

My thanks to the good folks at IXIASOFT, who allow me time for projects such as this and for the time I spend attending the meetings of and generally contributing to the efforts of the OASIS Lightweight DITA Sub-committee.

About

"DITAWriter" is Keith Schengili-Roberts. I work for AMD as a Senior Manager for Technical Documentation, and have recently helped usher in a new company-wide DITA-based CCMS. And I like to write about DITA and the technical writing community. To get ahold of me you can email me at: keith@ditawriter.com.

View all posts by