bobdc.blog

Excellent summary. I'll add that I do think DITA's relatively strict definition of topic, which in turn enables the use of DITA maps across a diverse range of content, is one of the reasons that DITA has been able to deliver scalable single-sourcing - something that has been traditionally promised by XML, but hard to achieve without a lot of planning and discipline (which DITA doesn't replace, but does provide a headstart with).

On the specialization front, anecdotally I've seen about half of DITA's adopters using specialization, which sounds like more than you've seen. A typical adoption curve is use DITA out-of-the-box for a year or two, then add some small-scale specializations, then begin building out additional specializations as you hit particular needs. In other words, you start simple, then evolve the architecture along with your understanding, rather than trying to do everything at once in the first adoption phase.

Thanks Michael! I like the idea of the headstart that doesn't replace planning and discipline. This could be a recurring theme when discussing a variety of aspects of DITA, ranging from the structure of maps to the transformations available in the DITA Open Toolkit.

Can you expand a bit on this comment about DITA relative to Docbook: "by limiting DITA's domain to be a little narrower than that of DocBook, its developers seem to have created something that appears less complex and therefore easier to use for people in that domain: topic-oriented technical documentation."

It was my impression that DocBook was actually more limited in the sense that is designed for a single technical narrative. It has a particular use case in mind, and is designed around that use case. DITA seems more like a toolkit approach for writing building blocks of documentation.

Is that right? If so, how do you see DITA's domain actually being narrower than DocBook?

That's what I meant by "topic-oriented technical documentation". There are lot of different elements that can serve as the root document of a Docbook document (book, article, etc.), so in my opinion it can be used in a broader range of cases than DITA. For example, a Docbook document could be organized by topic (or some rough equivalent) with less shoe-horning than would be necessary if using DITA for a narrative document.

This reduced amount of flexibility in DITA makes it easier for people to get a handle on exactly what good it can do them--sometimes extra flexibility is is more work for people as they figure out what profiles are available and which fits their needs best.

I think the distinction is appropriate (topic-oriented vs. narrative-oriented), but I'm not sure about which is broader these days, or which is easier to adapt towards the other.

Topic-oriented info is pretty much the norm for any professional tech pubs group, and with the rise of wikis and component-oriented CMSs it's rapidly becoming the norm for most new content on the Web or intranet. This doesn't mean that narrative content goes away, but I do think the broader use case probably is topics these days.

While it's hard to disagree with a man as likable as Mike Priestley, I believe the "DITA is for topics/DocBook is for narratives" meme is a false dichotomy. Nothing prevents you from writing effective, topic-oriented content with DocBook. As a technical communicator who uses DocBook every day, it's the only way I work. DocBook gives you everything you need to write granular, topic-oriented content. You can detail a task, reference information or a concept, recurse the heck out of it within your document (online help, web page, pdf, or whatever) reuse it in other documents, or stick that bit of content in a CMS and do all those things you'd expect that system to do.

Mr. DuCharme's old wine, new bottle argument is spot on. I've long asserted that DITA's "hotness" has more to do with the marketing dollars spent by IBM and the rest of the vendor community, than with any intrinsic feature or function DITA provides. While there may be specific reasons for one person to prefer DITA over DocBook, my experience tells me that it is largely about preference. One might prefer DITA because it seems simpler than DocBook ("Martha, just look at all those tags!); seems more suited to online work ("DocBook? We don' nee no estinkin' books!"); or, because it seems more appropriate for writing topics ("Our help is organized by topics, except when we publish it as a PDF; then, it's a narrative."). All these are fine and appropriate reasons, but none of them have anything to do with one standard having more juice than the other.

Yes, yes. I know. Except for specialization:

DITAdroid: "That's right. You can specialize with DITA. That way, when you're entire enterprise writes everything in DITA, you'll be able to use the Development team's use cases in the Marketing team's white papers."

You: "The whole enterprise writes in DITA? Even marketing?"

DITAdroid: "Yeah. Isn't it great!"

You: "Yeah, except, if you choose DITA because it
is "easier," then why would you wade in the deep
waters of specialization?"

DITAdroid: "Because, silly, once you get
experience with DITA, it's SOOO much easier
to specialize."

You: "Right, just like with DocBook. Once you
gain experience with it, the full range of its
possibilities for writing reusable,
topic-oriented, online content, and even - gasp -
narrative-oriented content destined for the
landfill (we called them books) becomes easier to
understand and implement."

DITAdroid: "No."

You: "Why?"

DITAdroid: "Because...Because the DITA guy told
me that DocBook is for books."

You :"Right."

DITA is cool. DITA rocks, rolls, and still loves you in the morning. Like any new love, she's hotter than the old one. But, is she really all that different? Not so much, I think.

IBM had topic-oriented authoring guidelines long before we had DITA; yet the move to DITA still caused shakeups and rewriting, because they forced teams to confront the issue of topics and chunking to fit their content in the architecture. One of the roles of XML is to enforce your content model - if your content model includes topic-orientation, it makes sense to use an XML architecture that includes that constraint, rather than punting to editorial guidelines on a key information model issue.

You don't mention DITA maps, which is interesting - I see them as a key component to the architecture, as important as topics or specialization. And maps don't work if you don't have predictable, addressable topics.

On the specialization front, generally people use specialization when they have business rules or information model constraints beyond just topic orientation that they want to enforce. That's why concept, task, and reference exist as specializations, along with all the user-created specializations out there, and why DITA subcommittees are actively developing industry-specific specializations. I recommend you read a few DITA specialization case studies, or ask on the dita-users list, if you want more detailed examples.

I like DocBook for what it does, but it doesn't enforce topics, it doesn't do maps, and it doesn't do specialization. If these three things don't matter to you, then you probably shouldn't consider DITA. But clearly they do matter to a lot of DITA users who are making active use of all three capabilities.

Just to add to what Michael said, Norm has shown that you could implement map- and topic-like constructs in Docbook, and it's very customizable, but these particular constructs are easier in DITA because of the head start it gives you if your information fits well into these structures. (That's why I liked his "head start" image.)

I'm sure that IBM has a budgeted strategy regarding it use of and participation in DITA work, but the term "marketing dollars" is a bit much--it's not an IBM product for sale like Websphere or DB2, but a standard that they support and want to see grow. I've written entire books in DocBook, and may write more, but in my role as an employee of a consulting firm that specializes in standards-based automated publishing, I see plenty of situations where DITA is more appropriate.

Mike, I appreciate your passion for DITA. I respect your deep knowledge of the standard and how it can support the work of technical communicators. I've been the beneficiary of your instruction and am happy to say that nearly everything (everything that's correct, anyway) I know about DITA, I first learned from you. Just so we're clear, I think DITA rocks. I don't believe I've ever once suggested that it fails to deliver the goods for online content (and, this latest iteration is well on its way to giving us more of what we need for print). If you say folks are falling over themselves to specialize, well more power to them - specialize away. And, while I can do the much same with DocBook, DITA maps are pretty neat, too.

My primary beef is that people who know better seem to consistently mischaracterize the capabilities of a mature, time-tested standard that continues to offer benefits to tens of thousands of users across the globe. These mischaracterizations end up misleading the uninitiated into believing that DocBook can't do what it can and isn't suited to do what it does. It may lead them to abandon an approach that gives them 99% of what they want and gives it to them as fast and as cheap as can be. I have a problem with that.

You know we can write topic oriented content in DocBook, and we can write narrative content in DITA. We can be as strict or as loosey goosey as our hearts desire. Whatever topic enforcement is purpose built into DITA (or, is not in DocBook) is only as strong as the willingness of the writer to obey those restrictions. There's no invisible hand guiding authors working in DITA compelling them to write tidy, compact and standalone topics. That's a skill to be learned, and - as you say - an approach that requires planning and discipline. DITA's "head start" might make it a bit easier, but it alone is not sufficient.

All I am saying is that it is misleading to assert that DocBook is unsuited for topic oriented content. That's demonstrably false. There may be plenty of reasons to choose DITA over DocBook (maps, specialization, hanging with the cool kids, whatever), but topic orientation is not an item where the two standards offer much of a difference. I've written books in DocBook, will write more, and as an owner of a consulting firm see situations where DocBook is more appropriate and situations where it is less appropriate. I don't have a horse in the race, and I owe my clients my objective opinion derived from a study of their requirements and the technical landscape. Other folks do have a vested interest in the growth and adoption of one standard, and when these folks consistently misrepresent and minimize the capabilities of a - like it or not - competing standard, that get's my attention.

As for IBM and marketing DITA, puh-leeze. Who employs Day, Priestley, Schell, Anderson, Hennum, Hunt, et. al.? Who pays their travel and perdiem at the dozen or so conferences they attend each year. Who sponsors these conferences, pays for developing the Toolkit and the Task Modeler, provides these folks time for writing articles in DeveloperWorks, etcetera? IBM. Every dollar they spend, compounded by the dollars spent by the dozens of smaller companies pushing their particular DITA "solution" is a marketing dollar for DITA. Why is it that so many folks of common sense and uncommon intelligence seem to squirm at the mere mention of this?

Tony, I gave you a concrete example of the difference between system-based topic orientation versus guideline-based. I am not slamming DocBook, I am reporting personal experience. That experience has been validated by dozens of other early DITA adopters, who have had to shake up content to fit it into DITA, and have benefitted from the result.

In terms of marketing dollars, my main job is not promoting DITA, nor is that the main job of the others you mentioned. We're fortunate to have supportive management, and in some cases conferences that are willing to help with the cost of travel to get us where we're needed. Does Norm Walsh's work on DocBook represent "marketing dollars" from Sun?

You're going to have to spread the credit for DITA's success much more widely. I'd start with the list of companies and individuals on the DITA TC page (which includes Sun, by the way).

You're so very right, Mike. Thanks for DITA. Thanks to the DITA TC membership for all your work. Thanks also to

Adobe Systems
BMC Software
Citrix Systems, Inc.
Comet Communication
Comtech Services, Inc.
IBM
Intel Corporation
Justsystems Corporation
Nokia Corporation
Oracle Corporation
PTC
Sun Microsystems
The Boeing Company
US Department of Defense

for their continuing investment in the work of these good people.

Thanks for DocBook, too. Thanks to Norm and Bob and the DocBook TC membership for all your work. Thanks also to

PTC
Reed Elsevier
Sun Microsystems

for their continuing investment in the work of these good people.

And, to all those people and organizations whose work benefits both communities, thanks and thanks again.

You've helped me feed my brain, feed my kids, and feed my wife's appetite for designer shoes!

I owe you, man. Big time.