One of the key questions when considering moving to the DITA authoring standard is: how is it different from what I have today? If you create technical documentation using a Help Authoring Tool, such as Flare or RoboHelp, you’ll probably want to compare DITA to these.
It’s not as easy a question to answer as you might think. As DITA is a standard rather than an authoring tool, you’re actually looking at two different things. However, let’s give it a go.
Similarities
[table id=1 /]
Differences
[table id=2 /]
Update
It’s been pointed out to me that there is a way of having a hierarchical structure inside an individual DITA topic, although you’d be stupid if you did so. The “composite topic” or “ditabase” is a DITA information type that can have topics within topics, and those topics can be arranged into a hierarchy. Ditabase pre-dates the ditamap.
Update 2
We’ve been asked about DITA and automatically “filling in” default metadata values in a topic. Strictly speaking, it doesn’t (although DITA authoring tools may have this feature), but it offers the same capability. DITA’s <defaultSubject> can be used to define a set of metadata values where none have be specified by the author. For example, you have product attributes: “Basic” and “Professional” for the Basic and Professional versions of your product. If there is a <defaultSubject> value of “Basic”, then the publishing processor will generate content using “Basic” setting for the product (i.e. it will generate a guide for the Basic version) unless the author explicitly has set a value (and no other inheritable value is set anywhere else).
Do you agree?
Do you agree with this summary? Anything we’ve missed? Please add your comments below.
Very useful comparison, thank you, Ellis! At first I shuddered, because technically speaking we’re comparing a data model with proprietary software products. But by emphasising that tech comm’ers look to each as a solution for their work environment, your comparison is very enlightening!
I would point out however that DITA and HATs doesn’t have to be an either/or decision! The company I work for was intrigued by many of the benefits and promises of DITA, but the migration of our unstructured legacy contents to DITA would’ve killed us. So what we did is we got ourselves a HAT (namely, MadCap Flare) and our own DITA-based information model.
Implementing “DITA half-way”, we get the best of both worlds: The ease of a standard HAT with its out-of-the-box workflows that can publish topics, even if they don’t validate according to the DITA standard. And the future opportunity to move to DITA more easily, once our topics follow our subset of DITA structures.
We have chosen Flare because it addresses some of the restrictions you list for HATs:
– Flare stores source content in valid XHTML in ASCII, so we can get at our sources and modify or convert them with scripts if we absolutely want to.
– We can re-use topics even across projects by project-linking, even if it’s not for the faint-hearted or seamless.
– We find it reasonably easy to incorporate Word contents and contributions by colleagues who don’t have a Flare license.
– We actually replicate DITA’s concept, task, and reference topic types in Flare.
I’ve written a blog post some time ago that explains our motivations and process in a bit more detail here: http://kaiweber.wordpress.com/2012/02/06/meeting-dita-half-way/
Thanks Kai. I guess we’re comparing information data models.
I would think “simon-pure” DITA would offer more robustness than a halfway house – it would be harder to break. You can do a lot with templates in an non-DITA environment, but if the writer decides to break the template, you have difficulties. With DITA you can validate the content.
You’re totally right, Ellis. One of our challenges was the need to introduce structure and an information model while having too much unstructured legacy content – we’re talking about more than 200,000 topics. So we needed a solution that allows us to write new topics with structure and to convert existing topics to structured content when not writing new topics.
Hello Ellis, and thank you for this list.
“DITA is an open format” has two practical implications: a) the specifications are public with no restrictions on use and b) you can share and open DITA source content using different tools.
I am not sure what differences you make here between metadata and conditions (first table), but with DITA, the authors can filter per metadata plus conditions and variants!
With standard formats, such as DITA, the advancement of the standard is led by an international group of companies (see OASIS consortium) not by one company as with proprietary formats. DITA has many inbuilt best practices, such as in the topic structure or the hazard statements.
aha – yes, you’re right Nolwenn.
Suppose I deploy a web-based application to two customers A and B. Both A and B have a “create account” page, only A has a “change password” page, and only B has a “change address” page. I would like to write a master document that describes all three topics (create account, change password, and change address), but create two different PDFs–one that includes A’s topics and one that includes only B’s topics. (I work at a company that has a more complex situation than this, but this is the bare-bones scenario.)
Is DITA appropriate for this environment? If so, can you point to some case studies? If not, what is the best authoring approach?
Yes, you can do this. See http://www.oxygenxml.com/dita/styleguide/webhelp-feedback/#Artefact/Metadata_Conditional/c_Select_Attributes.html and Dita Maps http://www.oxygenxml.com/dita/styleguide/webhelp-feedback/#Artefact/Maps/c_Working_with_Map_Files.html
Hi Ellis – I was reading your topic-based authoring blog and found a link to this one, which was exactly what I was looking for! I’d find it very helpful to hear a comment about structured vs unstructured in this context too. Kai touches on it: ” too much unstructured legacy content – we’re talking about more than 200,000 topics. So we needed a solution that allows us to write new topics with structure and to convert existing topics to structured content when not writing new topics”.
What is it exactly that makes DITA content always “structured”, and what is it in HAT’s which makes content “sometimes, kind of, but not necessarily structured”?
Thanks, Diana
It’s that topics are “Typed” (Darwin Information Typing Architecture). They must contain certain elements, there are rules as to order of how information appears, there are rules on the hierarchy inside topics, and so on.
In fact, there’s very little hierarchy inside a topic. DITA encourages you to start a new topic and manage the ordering and hierarchy using Information Maps.
With Help Authoring Tool topics, in comparison, you can have conceptual information mixed in with procedures, sub-headings and sub-sub-headings, which makes it harder to have a consistent level of topic granularity.
Thanks Ellis.