To boldly go where no tech writer has gone before (one can dream, right?)

The 5-minute DITA crash course

(This post is part of the Learn DITA on Your Own series.)

Before you can create your first DITA project (the “World’s Smallest DITA Project”, which will be the content of my next post), you need to have a basic understanding of DITA. There are tons of articles on the topic, but many of them focus on the advantages of DITA, its business case, or the benefits of single-source documentation. That’s all well and good, but our objective here is to learn how to write documents using DITA. Therefore, let’s get started with the following article, written by Chris Benz:

http://www.learningsolutionsmag.com/articles/524/what-is-dita-and-why-should-you-care

This article provides a great overview of DITA and its main concepts. Note that it was written for instructional developers and trainers, so you can skip the introductory paragraphs, jump directly to “What is DITA?”, and stop reading at “What is the DITA L&TC Specialization?” (unless you’re an instructional developer, in which case you’ll find this section very interesting).

So now I’m going to assume that you’ve read the article and know some of the basic DITA concepts :)

In summary:

  • DITA is designed to support topic-based writing.
  • It’s based on XML.
  • There are two types of DITA documents:
    • Topics: This is where you write your content. There are three types of topics: concepts, tasks, and references.
    • Maps: They assemble the topics in hierarchies for publishing various output formats. If you’re familiar with FrameMaker, you could see the map as the book file and the topics as the individual files.
  • You write your content in an XML file using a DITA editor. If you’re feeling really geeky (and there’s nothing wrong with that!), you can write your content directly in the DITA file, using a tool such as Notepad++, and typing the XML tags yourself. But many DITA editors provide visual interfaces that let you enter text very easily.
  • To generate your DITA content into the output format of your choice, you need a DITA publishing engine (such as the open-source DITA-OT).

Now you know enough to get started! In my next post, I’ll take you through the whole process of writing a topic, creating a map, and generating your output. You’ll create the ”World’s Smallest DITA Project” and go through the following steps:

  • Download and install a DITA editor
  • Download and install the DITA-OT
  • Create a topic
  • Create a map
  • Generate the map into PDF and HTML

Coming next week: The World’s Smallest DITA Project.


For the more curious

If you’re ready for more DITA and can’t wait until the next post, you can watch this five-minute presentation:

http://www.ditausers.org/training/DITATopics/

It provides a very nice high-level crash course on the DITA language.

Share this article:
Facebook Twitter Email Linkedin

4 Responses to “The 5-minute DITA crash course”

  1. Jeanne says:

    Hi Nathalie,

    I’ve read and bookmarked both links you provided and I’m ready for the next step!

    Knowledge of HTML (and particularly of HTML5 semantic elements) is going to come in handy, I see. I can imagine, as Chris suggests, that DITA maps can get very complex. That might be the trickiest part of all.

    Thanks! Jeanne

    • Nathalie says:

      Yes, DITA maps can get quite complex! It then becomes an issue of content management more than a DITA issue. When you start planning your DITA deliverables, the most important step is to determine how you will organize your content so that it makes sense, it is reusable, and it can be easily maintained. Only then can you create maps!

  2. Craig Wright says:

    Hi Nathalie,

    The Learning Solutions article that you refer to for the introduction to DITA concepts is excellent. Exactly the sort of entry-level information I was looking for.

    I wonder how large organisations manage the maps too. Especially for new writers that join – it seems to me that writers need an easy way to discover what topics and maps are already available and where/how to find them. In smaller teams, that is probably quite easy, but I’m sure it can get messy in larger, multi-department organisations. Do you have experience of working on large projects with many contributors?

    • Nathalie says:

      I’m glad you found the article useful, Craig.

      You’re right, managing maps can be quite a challenge for larger organizations. This is where information architects come in; they are the ones who organize the information, develop the maps, and assign topics to writers.

      I’m currently the only writer in the company, so I manage my own maps. But my company (IXIASOFT) produces a DITA Content Management System that targets large documentation organizations, so our tool includes utilities that help manage large maps (such as a collaborative reviewer, an assignment management tool, etc.).

      Thanks for reading!

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>