Testing DITA 2.0 with a 1952 Studebaker

While the DITA 2.0 specification is still a work in progress by the members of the OASIS DITA Technical Committee (which once included myself), it is getting close. At the time of writing (late October 2026), there’s enough of the draft available to do something useful with, and just as importantly, the latest release of the DITA Open Toolkit (4.4.1) can process much of it. Until recently, though, it was hard to try any of it. You could read the specification, but there was nowhere to see the new elements doing real work in a real publication.

That matters because a couple of my clients have started asking whether they should move to DITA 2.0 straightaway, rather than starting out in DITA 1.3 and then having to convert later. It’s a fair question, and I wanted something concrete to answer it with. So I built a test document: a complete DITA 2.0 bookmap containing 84 topics and 31 glossary entries, arranged in 12 chapters, that uses as many of the new DITA 2.0 elements as the Toolkit will currently handle. It is meant primarily for training purposes, and as sample content to run through your own plug-ins and output formats.

This continues some earlier experiments relating to content conversion. In Converting Content and Coding DITA with Claude AI and Converting Model T Content Using Claude AI I had Claude convert old Project Gutenberg manuals into DITA 1.3 (the Model T ended up as 179 topics), and in The How and Why of DITA Keys I used a TRS-80 manual to show how keys work. This time the aim was to see how far the same approach goes with DITA 2.0, and, as you will see below, with a rather different way of working with Claude.

One personal note: strong and em, which started life as my own proposal to the Technical Committee, are in this document throughout. It was satisfying to finally use them in a real manual.

The Source: A 1952 Studebaker Car Manual

For test content I needed something large enough to be realistic, already structured enough to adequately make use of DITA topic typing, and free to use. As with my earlier conversions, an out-of-copyright manual from Project Gutenberg fit the bill. This time I chose Your 1952 Champion Owner’s Guide (the Studebaker Champion), available as Project Gutenberg eBook 62925. It has chapters, procedures, warnings, tables, diagrams, a vocabulary that begs for a glossary, and an index, so every DITA topic type has a natural home.

Starting with the HTML version from the Gutenberg website, I first built the topic list from the table of contents, adding new content only where a single section mixed more than one type of information. The result is (not surprisingly) mostly tasks, with concepts and references where the text explains or lists things, and a handful of troubleshooting topics.

I kept the original wording as much as I could, but coming up with a exact one-to-one conversion was never the intention. Where a DITA 2.0 feature needed something the 1952 booklet could not provide, I added it. The clearest example of this is the multimedia page: the new ways of adding sound and video are major additions to the existing DITA 2.0 specification, and of course a original 1952 owner’s guide would not have either audio or video. The new additional topic contains sound and video clips purely to exercise those new media elements. Some troubleshooting topics, hazard statements and tables were also written or expanded to show off elements the original had no use for. Please treat the content as a demonstration, and not as a reliable guide to servicing your old Studebaker.

Planning the Conversion

Before writing any DITA I came up with a proposed topic list, based mainly on the manual’s table of contents, with a topic type against each entry. Several things came out of that exercise:

• Tasks first. Apart from one short reference topic at the start, almost everything became a task wherever the text described a procedure. Procedures like checking the oil, jacking up the car, raising the top and adjusting the pedals all read naturally as steps.
• Troubleshooting is its own type. DITA has a dedicated troubleshooting topic type (first introduced in DITA 1.3), so the original “what to do if” passages were converted to it and extended with extra content. DITA 2.0 adds a diagnostics element to that topic type. I wanted to show that off in a practical example, so six of the troubleshooting topics use it. The point was more to show off DITA 2.0 features when possible rather than trying to adhere strictly to the original text.
• Hazards live with the steps. The manual’s warnings were merged into the task topics they belong to, and became hazardstatement elements rather than free-standing notes.
• The index is not a topic. The index at the back of the original manual was not considered to be added as a topic, because the output processor rebuilds it from indexterm elements.
• One bookmap holds it all. The document lives in a bookmap, with every topic reference converted to a key reference.

The finished manual contains 84 topics and 31 glossary entries.

The DITA 2.0 Features in the Manual

Every topic file begins with a comment listing the DITA 2.0 features it uses, so you can open any file and see what to look for. Don’t consider the inventory below a complete tour of DITA 2.0; it is what DITA-OT 4.4.1 allowed me to test.

Feature	How it is used in the manual
strong and em	Replace b and i throughout.
alt as an element	Every image carries its alternative text in an <alt> child, since the DITA 1.3 @alt attribute is gone.
Simple tables with spans	Specification and reference tables, including the lubrication chart.
hazardstatement	Warnings and cautions are added to the relevant task topics.
diagnostics	New in DITA 2.0. This is an optional section in the troubleshooting topics, between the condition and the solutions, that says what normal looks like before the reader picks a remedy. Six topics use it, such as the ammeter reading.
mapresources	The bookmap pulls in its key definitions and subject scheme through this element.
keytext and value keys	Company name, product name, and values such as tire pressures, warranty periods and the tire-rotation interval live in a keystore map and are referenced by key.
Part numbers (partno)	Existing part numbers in the text, each tied to a key and described in a comment.
Hardware controls (hwcontrol)	Gearshift positions, pedals, switches and other controls in the driving topics.
titlealt and titlehint	Alternative and hint titles on selected topics.
linktitle	Link text for the cross-references to the source on Project Gutenberg.
subtitle	Chapter and appendix subtitles in the bookmap, so the long original titles can be split.
include	A description pulled from a separate text file, a line-range include, and the text of a Markdown file.
audio, video, media-source, video-poster, fallback	A dedicated multimedia page with MP3 and MP4 as the primary files and OGG and WebM as backups.
chunk="combine" and chunk="split"	A group of interior and body-fitting topics combine into one; the seasons topic splits into several.
resourceid with @appid-role	Identifies topics to an external application.
keyscope	Fall and spring scopes each define their own winter-preparation key.
conrefend	Conref ranges that pull a run of list items rather than a single element.
Subject scheme map	Defines season values for conditional processing.
DITAVAL @add-outputclass	Fall, spring and no-seasons filters add a class to the output.
Markdown topic	A topic authored in Markdown and processed alongside the DITA.
Glossary entries	Around thirty glossentry topics, referenced with abbreviated-form.

Two editions come from the same source. The “fall” and “spring” editions use DITAVAL filtering based on @otherprops. A third, “no-seasons” edition filters out the seasonal material entirely, which tests the subject scheme and the DITAVAL features together.

Keys, Reuse and the Keystore

One of the first decisions was to turn every topic reference in the bookmap into a key reference, and to keep the key definitions in a separate keystore map that the bookmap pulls in with mapresources.

The keystore holds three kinds of definition:

• Names and values. The company name, short company name, product name and full product name, along with figures such as tire pressures, brake and clutch pedal free travel, the tire-rotation interval and the warranty period in days and miles. Each is defined with keytext in the key’s topicmeta, and the topics refer to them by key. Change a number once and every topic follows.
• Part numbers. Twelve part numbers are held as keys, each wrapped in partno where it appears. I applied partno only to numbers that already existed in the manual, and each key is preceded by a comment explaining what the number is for.
• External links. The link to the Project Gutenberg eBook is a key with scope="external", so its wording and address are maintained in one place.

These could easily be put into separate keystores, but for simplicity’s sake I left them in a single keystore.

Reusable content is pulled in from one topic to another through conkeyref rather than copied. If you want the long version of why this matters, see my earlier article on The How and Why of DITA Keys. My original advice still holds: keys are most useful where something genuinely changes or repeats (or is expected to over time).

Multimedia: Sound and Video in a 1952 Car Manual

The manual has a page near the end whose only job is to show how audio and video work in DITA 2.0. It is a clear and obvious departure from the original, since nothing in a 1952 owner’s guide would be expected to play a sound, much less an embedded video. It uses the new audio and video elements with media-source children, so each clip has a primary file (MP3 and MP4) and a backup (OGG and WebM). A fallback element carries the text a reader sees if their output cannot play the media, and a video-poster supplies a still frame. The files live in their own multimedia folder.

The HTML5 transform handles this well once you know its quirks: it copies @format straight into the HTML type attribute, so the formats have to be written as MIME types. The PDF output cannot play anything and simply shows the fallback text.

Chunking, includes and Markdown

There are two chunking examples to demonstrate the chunk attribute. A group of interior and body-fittings topics use chunk="combine", so several small topics appear as one page in the output. The seasons chapter uses chunk="split", which does the opposite and breaks one source file into several output pages. I found chunking to be pretty fiddly to get right. Putting chunk on a topichead broke relative image paths and key definitions for the children, so the working version had to use a real parent topic with its children referenced by @href.

The include element is used in three ways. The long description of the wiring diagram is held in a separate text file and pulled back into the figure with parse="text". A second example uses a line-range include to bring in only part of a file. And a Markdown page, authored as a Markdown topic with format="markdown", has its text included into a second topic, which shows DITA and Markdown working side by side.

Editions: Conditional Processing and Subject Schemes

The manual includes advice that differs by season, such as preparing the car for winter. Elements for fall and spring are marked with @otherprops, and three DITAVAL files produce a fall edition, a spring edition and a no-seasons edition. A subject scheme map defines the values used for that attribute. The keyscope example works alongside this: the fall and spring scopes each define a winter-prep key with different text, and the same key reference resolves differently depending on where it appears.

The DITAVAL files also use @add-outputclass, which adds a class to flagged content in the output so a stylesheet can highlight it. I also built a small separate map to test the new cascade behaviour, but DITA-OT 4.4.1 ignores cascade="nomerge", so it is documented as a finding rather than a working feature.

The Limits of DITA-OT 4.4.1

To be fair, a test build is only useful if it tells you what doesn’t work yet. Here are my findings, all with DITA-OT 4.4.1:

• PDF and hardware elements. The PDF output has no formatting for the hardware domain, so hwcontrol and partno print as plain text. This is not necessarily a “problem” per se, as it is arguably up to whatever in-house formatting is wanted for these types of things, and the DITA 2.0 draft specification is not trying to be prescriptive here. HTML5 does write them as classed spans, so a stylesheet can pick them up and easily change them into whatever formatting is wanted.
• Alternative titles and subtitles. titlealt, titlehint, linktitle and subtitle are valid and accepted, but not output by the standard transforms.
• Media. HTML5 copies @format into the HTML type attribute, so media formats must be MIME types such as audio/mpeg rather than “mp3”. video-poster is not rendered, and a desc inside audio or video raises a warning. A media-track with an @href crashed my HTML5 build, so the manual shows that markup in a code block instead.
• Chunking. Children of a chunked topichead lose their key definitions and link targets, so the combine example hangs off a real parent topic and references its children by @href.
• include. It works with parse=”text” and line ranges, but not inside shortdesc, and parse="xml" did not behave. cascade="nomerge" is ignored.
• Fonts. The PDF font I am using lacks the check-mark and star glyphs, so the lubrication chart uses a small inline image for its check marks. Definitely not an issue with the DITA-OT, but worth pointing out.

None of this is meant as criticism. This is exactly the sort of thing a good sample, test output document ought to produce, and provides plug-in developers with a clear list of gaps.

The Process: Using Claude Code Instead of a Chat Window

In my earlier articles I used Claude’s free chat plan, pasting in one topic’s worth of manual at a time and then pasting the result into Oxygen to validate it. This project was different. For my clients I have a subscription to a professional plan for using Claude Code, which works directly on a folder of files, runs commands, and can look at the results of what it ran. Because the project’s files, notes and scripts were always in front of it, most (but not all) of the “no holistic view” problem I complained about previous just went away. I did not write the document by hand. The important word here is iterative: it grew in small steps over many rounds, and the goal throughout was to produce helpful examples of how DITA 2.0 works in practice, not simply to get a manual converted.

I started by giving Claude the draft DITA 2.0 specification, the DITA-OT 4.4.1 release notes and the zipped HTML of the manual, along with one rule: use DITA 2.0 only where the Toolkit supports it. Claude installed DITA-OT 4.4.1 in its own workspace, so every file could be built to PDF and HTML5 straight away against the DITA 2.0 DTDs that ship with the Toolkit, instead of just being written and hoped for.

The work followed the same cycle again and again:

1. Propose. Claude examined the source and proposed a topic list with topic types. I made decisions on the open points, such as keeping a short initial reference topic, converting a section to troubleshooting, and merging the warnings into the tasks.
2. Convert. Claude converted the manual one chapter at a time, and after each chapter I asked for more DITA 2.0: use simple tables with spans, use strong and em instead of b and i, use the new elements wherever they make sense.
3. Build. Every change was run through DITA-OT to produce PDF and HTML5 output. Claude then looked at the results: it read the build logs and rendered PDF pages as images to see what the output really looked like.
4. Find the limits. When a feature failed or rendered badly, we made note of it. Most of the limits listed in this article were discovered this way, and several were found only by looking at the rendered page, such as the checkmark glyph that printed as a “#”.
5. Document. Claude recorded each feature as it went, in the notes, in a feature write-up, and in a comment placed at the top of every topic file saying which DITA 2.0 features it uses, intended specifically for users to understand exactly what aspects of DITA 2.0 were being used and where. A script re-applies those comments whenever a topic changes.

The direction came from me, one question at a time. After the first full conversion I asked whether the manual covered everything DITA-OT 4.4.1 could do. Claude produced a gap list, and we then worked through it one feature at a time: hwcontrol, then partno, then alternative titles, linktitle, subtitle and include. I supplied the multimedia files and asked for a page that showed them off. Some suggestions Claude made were accepted as they stood, and others I redirected. When I felt the keystore had too many car terms in it, I asked Claude to take them out. When the images were too small to read in the PDF, I asked for them to span the page. When a feature turned out not to work, such as the DITA 2.0 learning topics, I told Claude to drop it.

The Human Factor (Still Required)

It would be misleading to suggest that Claude got everything right the first time. As with my earlier conversions, a lot of the value came from checking the output and correcting it. Here is what went wrong:

• Invented or wrong DITA. The learning topic Claude first wrote for DITA 2.0 used the wrong public identifier and element names with stray suffixes. The Toolkit does not ship the 2.0 learning grammars anyway, so that material was dropped.
• Markup that built but broke the output. A media-track with an @href crashed the HTML5 build. Putting chunk on a topichead broke image paths and links to the children. Both were found only by running the build.
• Problems you only see in the output. A check mark character printed as “#” in the PDF because the font lacked the glyph, and the star character had the same problem. Neither error showed up in the DITA, which is why Claude rendered PDF pages as images and checked them.
• Small mistakes. A hood control mark was keyed with the wrong value until I noticed, a comment in a test map contained a double hyphen that made the file not well-formed, and one of the helper scripts failed on a formatting error.
• Loss of context. Over a long project, decisions made early, such as which control names should be keys, needed revisiting once I could see the whole keystore.

None of these was hard to fix once found, but each needed someone to build, look and decide. That matches what I found with the Model T: the AI is fast and capable, and human validation is still part of the job.

The biggest difference from my earlier experiments was the loop. In a chat window the AI produces code and you carry it to a validator and back again. Here Claude built the output itself, read the errors, looked at the rendered pages, and fixed what it could before I saw anything. That means every feature in the manual was tried in a real build, so each claim in this article about what works is backed by an actual run. And because Claude kept notes as it went, the repository explains itself: you can open a file, read what it demonstrates, and see how it came out in the output.

That said, I wouldn’t hand a project like this to an AI and just walk away, expecting the end result when I got back to be perfect. Claude is quick at the mechanical work, such as converting thirty-seven task topics, regenerating maps and re-running builds. Deciding which features are worth demonstrating, and when a result is good enough, is editorial judgement, and that stayed with me. As I concluded last time, it still needs a person to check and guide its efforts, but the process is already fast and accurate enough (and much improved!) to be genuinely useful.

Try it Yourself

The source DITA 2.0 code is on GitHub: Champion_DITA_20_Car_Manual. The README explains how to run the DITA-OT 4.4.1 builds for PDF, HTML5 and the three editions. Note that the project uses the draft DITA 2.0 DTDs shipped with the Toolkit, which will undoubtedly change (though hopefully not too much!) as the specification is finalized.

If you are thinking of building your own DITA 2.0 test set, my advice is:

• Start small. Convert one chapter, build it, and check the output before going further. Problems are much cheaper to find early.
• Pin your Toolkit version. The 2.0 grammar is a draft and Toolkit support is changing from release to release, so record which version you tested with.
• Look at the output, not just the validation. Several of the issues in this article only showed up in the rendered PDF or HTML.
• Record what fails. A feature that does not work yet is a useful result, so keep the finding along with the fix.
• Use keys where content really repeats. As with most of DITA, they pay off for values that change or recur, not for every term.

In the \Studebaker DITA 2.0 Manual\champion\out folder you will find within the repository are examples of HTML5 and PDF output that you can check your own results against. There are also the spring, fall, and non seasons variants of the document available there for comparison.

If you run a different plug-in or output format over it and find something that breaks, or something that works that I haven’t covered, I would like to hear about it. That is precisely what the document is for.