This has been a project I have been devoting time to for over the past year. It is a DITA-fied version of a full manual, in this case, a vintage, WWII-era pilot’s guide to the B-25 “Mitchell” bomber. You can find all of the DITA source files on GitHub, and there is an additional Markdown-DITA version for those who want to play with some Lightweight DITA code. My thanks to Scott Hudson and Eliot Kimber for their extensive contributions to this effort.
How it All Began
This project began out of a general request from the DITA Listening Sessions hosted by The DITA Adoption Committee for more practical samples in DITA format. I knew that there wasn’t anything that currently existed for aviation, so I set out to see if there were any old, out-of-copyright manuals in this area that might easily lend themselves to being DITA-fied. In addition to being out-of-copyright, it also had to be of a “medium” size (not too small so that you could not usefully show off some DITA features fully, but not too long that it would take forever to convert), and written in a way that was already topic-like in its structure. This excluded some early manuals on flight that tended to be more narrative in tone (but make for some entertaining reading. In the end, the B-25 Pilot Training Manual best fits the bill. It was a real manual, not so technical that it would turn away most casual readers, and had plenty of illustrations making it not text-heavy. The historical angle was also a plus, and reading it gives you an extra appreciation of what the pilot and crews had to know in order to effectively fly this tricycle-wheeled monoplane. Having said that, it is worth pointing out that this a piece of war machinery: while much of the focus is on flight mechanics, there are sections on such things as how to do a chemical bombing run. (For reasons that should be obvious, this MDITA example code was turned down by a colleague who was presenting at a DITA forum in Japan).
Multiple Uses for DITA Keys
Keys were used in several ways within this document. First, they are used to cover the series number of the airplane (known as a “designator”), which in this case is “B-25”. Keys ensure consistency within a publication, so using a key for the designator prevents the writer from accidentally typing an incorrect variant, like “B 25”, “B25”, or “B-52“. If the original writers somehow were using DITA back in the 1940s, they could have likely reused much of the existing content for the subsequent B-26 “Marauder” and update the key in the reused topics to match the new designator. Keys were also used in constructing the glossary (they are required in any glossarylist), and in the key warehouse for storing the images.
Using a Key Warehouse for the Images
This was an idea promoted by the “Father of DITA Keys”, Eliot Kimber. The purpose of this function is to demonstrate how images can be reused by utilizing a key mechanism, providing each image with a name that can then be called within a topic. The key store is a map file containing all of the key definitions and the URLs of the images they point to. From what I have seen this is a widely-utilized way to manage images (especially if you are not using a CCMS), but it is rare to see used in such a comprehensive way in sample code, which is why we did it. The only real shame is that in the original manual there were maybe only one or two images that were used more than once, though this strategy would be useful if one was tackling an update of this manual that reused many of the original images.
Lots of Short Descriptions
While what you see matches the original document as much as possible, a few liberties were taken to show off DITA features that would not have been possible at the time the manual was originally written. One of these ways was to add short descriptions to each topic. While it would have been easier to simply incorporate the first sentence of each topic, this is definitely not a best practice, so time and care were taken to write custom short descriptions for each topic in the manual. If done correctly, it should aid the reader to discover which topic within the manual is the one they are looking for.
Multimedia and DITA
Another way that we broke from the original content was by adding some multimedia elements embedded into a few topics. For example, there is a YouTube video of what was originally a training film for pilots of the B-25, portions of which were clearly based on the original manual. Back in April 2019, I used these topics to demonstrate how multimedia can be usefully inserted into DITA topics, in a presentation I did with Leigh White. Part of the focus of the talk was on the upcoming multimedia elements that are already part of the draft version of Lightweight DITA and will be coming to DITA 2.0.
Lots of Relationship Tables
Few public DITA code samples delve into relationship tables. Relationship tables provide links to related material on a per topic basis, providing an alternate way of linking to other topics via xref links. Whereas inline xrefs tend to draw the reader away from the text, relationship tables provide a set of “See also:” type links. In this case, we opted to link each topic within a chapter to all other topics within that same chapter. This is definitely overkill for topics in some of the lengthier chapters, but the idea was to produce an extensive example as to how relationship tables can be deployed.
Other DITA-specific features within this manual include:
- A robust ditamap bookmap, including all relevant metadata, plus frontmatter and back matter material
- The main bookmap (pilot_training_manual_for_the_mitchell_bomber.ditamap) contains lots of comments, describing each section of the manual
- Each image is fully described according to accessibility best practices (encapsulated within a set of fig elements, including a title, description, and an alternate description)
- Keywords added as metadata to each topic
- Fully accessible tables, using @rowheader
About the MDITA Version
Once the final release version of the main DITA version of the document was ready, DITA Adoption member Scott Hudson undertook the task of converting the content over to MDITA, the Lightweight version of DITA using the Markdown format. So if you are looking for an extensive example of MDITA code to check against or for testing purposes, look no further than the version posted here.
Some Final Thoughts
If I were starting over, there are a couple of things I would consider re-doing:
- Make the numerous checklists that appear within the document a specialization of task
- By default we had to use the uicontrol element to handle a wide range of instrument controls, ranging from push buttons to multi-channel selectors, levers and foot controls which don’t fully square with the software controls encompasses by uicontrol. This has contributed to a good discussion at the DITA TC about non-computer controls. It’s too early at this stage to know if you are likely to see an (example) element anytime soon, but if it does this document was part of the reason that led to it.
This material is also freely editable. If you find other ways to improve the sample content, please go right ahead.
We at DITA Adoption hope that you find this sample code useful for learning and using DITA. We hope you earn your wings flying with DITA! 😉
Note: for the moment the files are being hosted in the DITAWriter GitHub repository, it will be moved to an OASIS GitHub repository for the DITA Adoption Technical Committee. All links in this article will change when the switchover is made.
