While there are a lot of code snippets and demos that look at aspects of writing DITA, it is still exceedingly rare to find good, publicly-available source code examples of entire documents written in DITA. That’s why I thought it worth mentioning Gnostyx‘s recent posting to GitHub: a demonstration document written in DITA, with a version written using DITA 1.2. This has been followed up by a couple of additional versions contributed by Eliot Kimber designed to show what he calls “potential best practices” for how keys and keyscopes can be used under DITA 1.3. These files are free for anyone to download and learn from.
I think this worth mentioning because up until now most people have had to muddle along learning DITA using either from scattered code snippets, or long-outdated (and short!) examples like the one that is included in the DITA-OT. It is worth pointing out that the intent with these files is not to show every possible feature of DITA, but instead to be a “realistic source”, providing an example of a document deliverable comparable to what can be expected in the real world. This demo user guide consists of four chapters describing the function of a fictitious computer clustering software application called “Thunderbird StormCluster”. Having produced similar documents myself I can attest that it is very close to the real deal. This document shows off a lot of the aspects of DITA 1.2, including good, working examples of:
- Keys
- Keyrefs
- Conkeyrefs
- Topicgroups
- A sample reltable.
There are also two additional versions that have been added by Eliot Kimber demonstrating how DITA keys and keyscopes in DITA 1.3 can work. One version adds keys to all refrences to topics so that there is one link reference per topic and each reference as an associated key; the second declares a resource-only key for every topic and image, and all topicref use keys/keyrefs for every topic referenced.
To download these example, simply go to the main dita-demo-content-collection page on GitHub and click for the “Download ZIP” button which appears at the bottom of the right-column of the page.
It is also worth mentioning that the folks at Scriptorium are devising sample learning content for DITA based on the Learning & Training specialization, which can also be found on GitHub.
I think it is great to have such publicly-available sample files for people to play and learn from, and I think many people will find these resources genuinely useful.
