This post is part of a series of posts that question some of the claims made about the benefits of DITA adoption.
(Note: DITA uses the word "topic" to refer to a reusable module of content. Out in the rest of the world the word topic tends to refer to an HTML page or a section of a PDF. This may be seen as an infuriating oversight, but I suspect it's actually deliberate. For a while I tried replacing DITA "topic" with "reusable module of content" but I have given up and now just use the one word to mean multiple things.)
I started with DITA several years ago when I got a job in a large doc team that had been using DITA for a while. I inherited a few deliverables and was appalled at the way the content was broken up into concept, task and code sample topics. We optimized for HTML output and there were too many brief HTML pages that users had to click through. Even for a simple idea that could have been covered in one paragraph, these docs would have three topics. For example, a description of how to stop the server would have a concept, task and sample topic, each appearing on separate HTML pages.
My audience was developers. I did quite a lot of usability testing with them and found they were furious about the documentation. They hated having to click through multiple tiny pages. They hated the minimalism and choppiness. They described the docs as unfriendly, officious, insulting and unhelpful.
I looked into chunking (the DITA way to combine multiple topics on an HTML page) but our CMS didn't support it. Even had I been able to use chunking, a topic was defined as a title and body, and frequently the titles would have got in the way of well-formed topics.
I ended up copying and pasting text into new, larger, restructured topics. It was an enormous pain because DITA dictates different elements in the different topic types. (Why oh why could DITA have not just used ul, ol, li and p consistently? Why stick us with steps and cmds and other nonsensical redundant elements? If anyone can answer that, I'd really like to know.)
After a lot of work I created a nice usable, readable help system made up completely of concept topics. My concepts included steps where needed, tables where needed, lots of code samples sprinkled throughout, and lots of sections with section headings. I was writing about advanced topics like cryptography and there was no potential for reuse (as there was no potential for reuse of most of our developer topics - DITA was brought in for the end user team).
I changed companies to another DITA shop and son of a gun, I inherited a gazillion tiny concept, task and reference topics. This time I was working in FrameMaker 9 and it doesn't support chunking either. I had more potential for reuse this time and so had to consider that in my rearchitecture, but I still returned to concepts.
When DITA gets criticized the DITAnistas invariably respond that DITA is not to blame. Another blogger wrote a very erudite post on this topic ( The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference), and a commenter wrote that DITA is like hamburger: if you don't like the meatloaf, don't blame the meat.
But the poor architecture I inherited is directly the fault of DITA. OASIS creates the DITA spec, and on the OASIS web site (eg docs.oasis-open.org/dita/v1.0/archspec/topicover.html), writers are told to create topics that way. In both companies, they simply did what OASIS told them to do.
It's true that I have the flexibility in DITA to organize my topics however I like. (That's nothing special: I could make equally free choices if I wrote in Docbook or raw HTML.) And I am always going to organize topics in the way I think they'll be most useful and attractive to my readers, as well as easiest for my reuse. What I would like is to not have to keep encountering DITA writing that is ugly, difficult for users, and difficult for me to change.