How does DITA compare to a Help Authoring Tool?

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

DITAHelp Authoring Tool
Content is written in topicsContent is written in topics
Content is organised for publication using mapsContent is organised for publication using Tables of Contents, and within the topics (using Headings)
It needs to be changed (published or transformed) into something readable for usersIt needs to be changed (published or transformed) into something readable for users
You can create different versions of manuals, based on metadataYou can create different versions of manuals, usually based on conditions
You can insert variable information into documents, using KeyrefsYou can insert variable information into documents, using variants
Formatting is always controlled outside of the topicFormatting is mostly controlled outside of the topic
Your links can change depending on the document or publication in which a topic is usedYour links can change depending on the document or publication in which a topic is used (in some HATs)

Differences

DITAHelp Authoring Tool (HAT)
DITA is an open standardHATs tend to use proprietary data storage standards
DITA content is always written using a markup languageHAT content is sometimes written using a markup language, but generally written using a WYSIWYG editor
You can re-use topics in different publications, and make those topics accessible to other writing teams who might want to re-use themYou can only re-use topics within your project in different publications
You can use a variety of different authoring tools, content management systems and publishing/rendering enginesYou can only use the HAT (although some enable you to incorporate external content written in Word, HTML or emails)
It’s easy to share DITA contentIt can be tricky to share content
There are different types of topics (“Information Types”)There's a single, general type of topic
There are strict rules regarding how the semantic markup in topics is writtenThere are not always strict rules regarding how the semantic markup in topics is written
You cannot have a hierarchical structure (Heading 1, Heading 2, Heading 3 etc) inside an individual DITA topicYou can have a hierarchical structure (Heading 1, Heading 2, Heading 3 etc) inside an individual topic
You can set up controlled vocabularies and taxonomies Only a few HATs enable you to set up controlled vocabularies and taxonomies
You can automatically “fill in” default metadata values in a topicIn most HATs you need to add the metadata manually
You can add customised content to a list without having to make any changes to that target topicYou cannot add customised content to a list without having to make any changes to that target topic (unless you have added placeholders beforehand)
You can replace content in a list without having to make any changes to that target topic You cannot replace content in a list without having to make any changes to that target topic

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.

10 thoughts on “How does DITA compare to a Help Authoring Tool?

  1. 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/

  2. 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.

  3. 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.

  4. 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.

  5. 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?

  6. 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

  7. 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.

Leave a Reply

Your email address will not be published. Required fields are marked *

CAPTCHA Image

*

Notify me of followup comments via e-mail. You can also subscribe without commenting.
http://www.cherryleaf.com/blog/2013/07/how-does-dita-compare-to-a-help-authoring-tool/comment-page-1/
www.cherryleaf.com
crawl=CC-MAIN-2015-35
51669
application/http; msgtype=response
sha1:STIY4BSXEXVSSMDPXQ47GDLPU62MYUTU
<urn:uuid:18987575-fca5-44f0-a0b2-13ef49f037ea>
2015-09-02T14:48:30Z
176.32.230.9
sha1:JOUVACNW5N45KV5NRTKICFDIEFEUOANW
<urn:uuid:99169478-44fc-442a-bd0b-ec0362e2b449>
http://www.cherryleaf.com/blog/2013/07/how-does-dita-compare-to-a-help-authoring-tool/comment-page-1/
length
response
<urn:uuid:839d2a73-9d8a-4e65-a6c2-691376966bff>
robots: classic
hostname: ip-10-171-96-226.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2015-35
operator: CommonCrawl Admin
description: Wide crawl of the web for August 2015
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf