This is the first guest-post here on DITAWriter. I read this piece written by long-time DITA advocate and SIGDOC secretary/treasurer Stan Doherty, originally intended for members of that largely academic forum. I thought that the piece ought to get wider circulation, so with Stan’s permission, I’m pleased to republish it here.
Between January 2025 and July 2026, seven new books have been published about OASIS DITA. All seven books have been available on Amazon, although two have recently been removed. Technical writing teams are looking at these publications. Trainers and college instructors are ordering these publications for their students.
• Aamalich, Moussa. DITA for Beginners, Amazon, May 2025 (hereafter “MAamalich-1”)
• Aamalich, Moussa. Mastering DITA, Amazon, May 2025 (hereafter “MAamalich-2”)
• Bradford, Wesley J.. DITA Publishing Handbook, Amazon N/A, 2026 (hereafter “WBradford”)
• Grant, Tyson C.. Mastering DITA Handbook, Amazon, May 2026 (hereafter “TGrant”)
• Konger, Snehasish. DITA Decoded, Amazon, January 2025 (hereafter “SKonger”)
• McCarthy, Ethan G.. Modern DITA Mastery, Amazon, July 2025 (hereafter “EMcCarthy”)
• McCarthy, William Z.. DITA Implementation Handbook, Amazon N/A, 2026 (hereafter “WMcCarthy”)
For the most part, these publications are compilations of GenAI-generated output about DITA and not original, human-informed content developed by experienced DITA professionals. We have entered something of a new era in textbook publishing. GenAI tools can produce significant quantities of content about a subject like DITA and someone without hands-on experience with that subject can assemble that generated content into a book and publish it without technical or editorial review. If we see seven new books on DITA as of this writing, more are coming.
I see two good reasons for reviewing these publications:
• Quality assessment: Teams and instructors needing reliable, high-quality content about DITA need to know where these publications fall short. Book buyers beware.
• Criteria for good publications: The elements so often lacking in these publications suggest what should be included in good books about DITA.
More of these books will be entering the market. I’ll do my best to provide updates and to post current reviews to modularwriting.com/dita-books.
Shared publication issues
These recent publications have much in common.
Authorship
Only two of the named authors are clearly identifiable from LinkedIn or social media as people: Moussa Aamalich and Snehasish Konger. Both are engineers with some level of connection to software companies. Neither appear to be DITA writers, architects, or implementers.
Publisher
All seven publications are listed as being published in New Haven, Connecticut without the name of a publishing corporation. For all practical purposes, these are self-published books without identifiable editors or reviewers. Two of the publications have the same cover art.
Page format
Except for MAamalich-1, MAamalich-2, and SKonger, the publications use the same 8.5″x11″ page format with exorbitant white space. The 300-page book in 8.5″x11″ format is at best 125 pages of content at 250 words/page.
Page elements
With few exceptions, these books present content almost entirely in bullet lists. Occasionally there may be a table or a diagram, but 95% of the content consists of a secondary heading followed by bulleted list items. Introductory text is occasionally relevant, but not insightful. Transitions between secondary headings are minimal, if present at all.
Running content format
It is my belief that most of this content consists of GenAI prompts (reformatted as secondary headings) and generated lists. I discovered very few technical diagrams and relatively few tables. Also missing were screen shots and real examples of generated output.
If it is correct that each section in this book were generated from separate GenAI prompts, that would explain the lack of transitions and cross-references between sections. Each section and sub-heading is siloed.
Redundancy
Within the same publication, there is often significant content and organizational redundancy. This is probably derivative from the high degree of content redundancy generated from the GenAI tools. The chapter names tend to be irrelevant if the content within any chapter touches on the same points over and over.
Content focus
These publications are actually useful in identifying the challenges involved with moving to structured authoring and DITA. It is difficult to read more than a page without encountering some variation of the following sentence: “You need to consider XYZ to succeed with DITA.” Rarely do the authors explain how to achieve XYZ or offer any personal experience with XYZ. If a team were amassing a list of migration issues, these books would be useful. The appropriate vocabulary is mostly there. Practical examples, solutions, and recommendations are less obvious.
Preliminaries
MAamalich-1 and MAamalich-2 offer no foreword, acknowledgements, or preface. SKonger offers a small one. The remaining four publications offer basically the same set of prelims with variant headings and wording. GenAI does a good job a reshuffling content that way.
Recurring sections
Several publications rely heavily on FAQ and Glossary sections – artifacts easily generated by AI. Other chapters focus on XML basics, DITA-OT, AI, and “new developments.” It is my suspicion the books are based on a common set of 30-40 GenAI prompts. The output is then shuffled around to make the ToCs seem to be different.
Errant tool recommendations and cross-references
To the extent that a lot of the underlying content in the GenAI LLMs is context-unaware or out-of-date, the derivative sections here offer a mix of relevant and grossly obsolete references. Recommending the long-dormant Serna XML Editor alongside the Oxygen and XMetal editors is a little scary.
MAamalich-1 recommends and misidentifies authors/titles for other DITA books, for example DITA 101 by Tony Self [actually by Ann Rockley, Charles Cooper and Steve Manning], DITA for Print by Michael Priestley [actually by Leigh White], and Learning DITA: A Beginners Guide by Derek Melber (an RSA specialist). Hallucination stuff.
Shared technical issues
There are plenty of red flags here.
Versions
Beyond EMcCarthy congratulating the DITA TC for releasing DITA 2.0 in 2023, there is little awareness of DITA versions, DITA-OT releases, or advancements in structured authoring in general. WMcCarthy dismisses DITA DTDs as a legacy grammar format and promotes schema/XSDs as the replacement. Three publications promote the notion of creating topic-to-topic @conrefs without organizing reusable content in dedicated library topics. Ah, life before keys.
Technical audience
For all the chit-chat in these publications about “mastering” this and that, most chapters in these publications confuse terminology and what is a required technical background. What a new writer needs to know this side of what an architect or implementer need to know is rarely clear. If these publications were based on later versions of GenAI tools, it would have been possible to specify technical backgrounds. Right in the prompt, you can now specify: “for a DITA beginner” or “for a DITA engineer” and so on.
Invalid XML DITA examples
Three publications offered no code examples beyond a couple of topic- type boilerplates. Another three publications were riddled with invalid examples. The most common problem was the lack of <body> container elements such as <conbody>, <taskbody>, or <refbody>. This was a frequent issue with ChatGPT output prior to version 5.5. Only WBradford seemed to have tested examples against a DITA parser. Either that or it derived examples from a more recent version of a GenAI tool that did a better job generating small, valid examples. I observed no complex examples, valid or invalid.
The lack of attention to DITA validation disqualifies these publications as being useful instructionally. Furthermore, new DITA writers cannot tell easily which examples are valid and which ones are bogus. Trust is important in this area.
Fictional elements and attributes
2025 and early 2026 GenAI tools produced pseudo-markup to illustrate a point. For example, these publications preserve bogus element names such as <dita-ot-configuration>, <conref>, or <warning>. Mysterious attribute names such as @output appear in places.
Incorrect DITA-OT and automation examples
The publications did a slightly better job illustrating DITA-OT command lines and related bash shell scripts. There was a general lack of awareness about DITA-OT support for Markdown or any of the 4.3 or 4.4 enhancements.
Missing or underdeveloped concepts
Some things that are important in any introduction to DITA get little or no no airtime: reuse libraries, subjectScheme maps, bookmaps (no mention), and Schematron.
Relative technical difficulty/complexity
Without hands-on experience with DITA features, the authors of these publications treat most DITA features as though they were of equal importance, equal complexity, and equal maintenance overhead. Three publications suggest that teams can increase reuse by adding filtering conditions to phrases, sentence fragments, and sentences. Who needs the messiness of keys when hundreds of @conrefs do the job? Similarly, two publications put scoped keys on the beginner, must-learn list. All writers should be able to create and debug reltables across enterprise publications.
By not prioritizing what new writers or new teams need to know, these publications implicitly suggest that you need to know everything. Suggestions that here may be specific tracks or learning paths through DITA are rare.
What to look for in a good DITA book
Well, one benefit of looking at all of these publications is that it clarifies many ingredients of a good book on DITA. FWIW–here’s what I look for–in no particular order or priority.
- Audience: No book need confine itself to one target audience, but calling out audience-specific learning paths, feature priorities, and advice meets readers half way. There is no generic DITA audience or all-encompassing DITA audience anymore.
- Authorship: I’d like to know a bit about who wrote the book. Has the person or persons had years of experience as a writer? architect? DITA engineer? When they make recommendations or offer a caution, it would be useful to know where that is coming from. What type of content have they worked with? How did DITA adapt to that type of content?
- Reviewers and acknowledgments: DITA is a community with many wonderful, generous, and supportive professionals. By definition, any draft of a book based on the experience on one person would benefit from other points of view. Publishing a book with no visible reviewers is short-sighted.
- Content and context: Probably one of the strengths of DITA is that it can shape content models around many different types of content: software, cloud, API docs, hardware, military, medical, networking, and so on. By reading multiple books authored by people who have worked in different fields, you can get a feel for how shape the many options in DITA to a particular content type and context. Sharing that level of experience explicitly helps.
- DITA spec awareness: The DITA Technical Committee focuses the spec on tool implementers and folks who customize DITA for their companies. The DITA spec is such an under-appreciated asset. Books that introduce DITA to beginner, intermediate, or expert audiences can and should leverage spec terminology, examples (where appropriate), and feature descriptions. Inventing new terminology or funging existing terminology helps no one. Futhermore, as we approach the publication of DITA 2.0, awareness of new features in 2.0 and migration paths from 1.3 should be in the mix somehow. As people new to DITA gain experience, they are going to want to become more familiar with the spec itself. Adding cross-references to the spec would encourage that without requiring readers to dive into the spec before they are ready.
- Meaningful, valid examples: Examples really should be developed by people who know what they are doing and reviewed by peer writers, architects, and DITA engineers. FWIW, I have found that well-documented, intelligible examples have more instructional merit than most anything else. GenAI may claim to produce valid markup, but it cannot run its generated markup through a parser. If the author of one of these books does not validate the examples, readers of the book will be required to do so. Readers must be able to trust the examples.
- Downloadable, testable examples: If an author has developed and validated meaningful examples, they should make them available to readers. This is especially useful when it comes to exemplifying complex DITA features that depend on map, topic, and metadata interdependencies.
- Learning paths and priorities: An axiom of topic-based authoring involves using short descriptions and topic titles to clue readers about the relevance of the information they are looking at. Similarly, proving explicit learning paths and notes to readers helps everyone–including the book authors. It’s OK to identify some features as super-basic and others as super-advanced. Most DITA writers use 10%-15% of the total canon of DITA elements. It’s important from an adoption point of view to let readers know that they can succeed as DITA writers without having to know everything.
- Visuals (diagrams and screen shots): Writing about DITA can be gritty stuff. Authors who make the effort to provide conceptual diagrams, useful tables, and screen shots get my vote for decreasing the tedium of walls of text.
DITAWriter: I’ll just add as a post-script that these books are deliberately not linked to from the DITAWriter website in this article, and will not appear in the listing of DITA Books.
