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

Learn DITA on Your Own: Plan your Training

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

Now that you have set up the tools and created your first DITA project, the real work begins.

Learning a new skill takes time and effort. We have the best intentions, but we also live busy lives. How many times have I bought a book with the intention of learning a new subject, read a few chapters, and then put the book aside, never to return to it? It’s not enough to have a goal; you must also put a specific training plan in place to achieve your goal. I’m a runner, and I know that if I want to achieve a new goal, whether it’s running a long cross-country race or establishing a new personal record, I need a plan.

So, how do you develop a plan for learning DITA?

1. Find a real project that you want to do in DITA

A real project will give you a purpose for completing your training. And since you’ll need content when creating different object types in DITA (such as tables, cross-references, procedures, etc.), without a specific project in mind, you may waste time trying to come up with content.

For example, you could convert one of your existing user manuals to DITA. You could also take content that is freely available on the web, under a Creative Commons license (which means that you are free to copy and redistribute the material in any medium or format, as long as you don’t use it for commercial purposes), and create a DITA version of it. To find such documentation, search for the following string in Google: “documentation is licensed under a Creative Commons Attribution”.

Another advantage of using a real project is that you can then include it in your portfolio to show potential employers (more on this in an upcoming post).

2. Buy a book

A great training book will explain the DITA concepts and provide exercises so that you can apply your knowledge. There are many books available, but here are my recommendations:

Introduction to DITA, Second Edition by JoAnn T. Hackos

intro-to-ditaThis book is a great introduction to DITA. It also includes 24 lessons that cover most DITA concepts, from creating a topic to creating a Ditaval file for processing. Throughout the book, you create a small user guide for a fictitious phone system. I recommend the electronic version (available from ComTech here), so that you can copy and paste code samples if you don’t want to type them out. (I can’t say that I particularly like the interface of the electronic version, but being able to copy and paste code makes is worth the not-so-friendly interface).

DITA Best Practices by Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt

DITA-Best-Practices

This is the perfect book for writers who aren’t too technical; the concepts are explained simply and clearly and the book is very easy to follow. The main problem with this book is that most examples are not provided in DITA code; instead, elements are displayed visually. This is great if you’re using a visual DITA editor; otherwise, it’s not that useful. Also, this book was released before DITA 1.2 was out, so it’s missing important 1.2 features such as keyrefs and conrefs. But it’s a great introduction to DITA.

<dita> for Practitioners by Eliott Kimber

dita_for_practitionersThis book is organized in two parts: The first one introduces the main DITA concepts and provides great tutorials that take you through the steps of creating DITA content and generating it using oXygen and the DITA Open Toolkit. The second part goes over each concept into more details. You can download the code samples used in the document so that you don’t have to type them. Two small warnings about this book: It uses the oXygen DITA editor in the examples, so while you can still create and run your content using Notepad++ and calling the DITA OT directly from the command-line, you’ll need to do a bit of work on your end to perform the procedures. Also, while this is probably my favorite DITA book, I read it once I already knew about DITA, so I’m not sure it’s the best introduction to DITA for writers. Kimber is a DITA guru and a very technical guy, so this book may be more difficult for the less technically inclined.

3. Determine a schedule and commit to it

Learning a new skill takes time. If I want to reach a race goal, I need to run at least three to four times a week. With work, family, and side projects, I’m very busy, so if I don’t plan ahead the times when I’ll go running, I don’t make it.

In the same way, you need to plan ahead your DITA training time. For example, you could plan to work on your DITA training every Tuesday evening, two evenings a week, or every second Saturday. The important thing is to select a time that is reasonable and doable for you, according to your schedule. Otherwise you may get discouraged and abandon your plan.

4. Make a list of skills that you need to learn

It’s not enough to simply plan when you’ll work on DITA; you also need to know what you will be learning! I recommend organizing your training around the book that you’ve selected and creating a spreadsheet that lists the DITA concepts covered in the book.

As an example, you can download here an Excel Spreadsheet that contains sample training plans for two of the books listed above, Introduction to DITA and <dita> for Practitioners. You can then use it to track your progress and see how well you’re doing.

(Optional!) 5. Invest in a tool such as oXygen Editor

While Notepad++ will work just fine to learn DITA, it will not check your DITA structure and does not provide a visual interface. I have been using oXygen for the past three years and I love it.  You can get the latest version for $349. It’s not cheap, but it’s not overly expensive, and you will be able to add oXygen to your list of skills. There are other XML editors available; the best up-to-date list of XML editors that provide DITA support is available through the DITA Writer, in his article List of DITA Optimized Editors. You can also request a one-month free trial license for most of these vendors.

Note that this is completely optional. You can very well use Notepad++ and run the DITA Open Toolkit from the command-line…you know it works, because you’ve done the World’s Smallest DITA Project using these tools!  The good news with Notepad++, though, is that you’ll be quite the expert in DITA authoring once you’re done with your training! If you plan to use Notepad++, the Introduction to DITA, Second Edition is probably your best choice in terms of book.

What’s next?


With a plan, a book, and the tools, you have all that you need to learn DITA on your own…now get to work! :)

In the next post, I’ll cover essential DITA blogs, user groups, and Twitter accounts that you should follow to get connected with the DITA community.

Share this article:
Facebook Twitter Email Linkedin

7 Responses to “Learn DITA on Your Own: Plan your Training”

  1. Jeanne says:

    Now is the hard part. All the previous posts were play compared to this one! Seriously, you’ve identified an important (perhaps the most important) part of the process.

    Thanks for getting us organized and motivated, Nathalie!

  2. Revathi says:

    Eagerly waiting for your next post in this series. Thanks for instilling the confidence to learn DITA.

  3. Peter says:

    Hi Natalie,

    I am not experienced in the DITA and XML authoring/editing method.

    Since it has been getting more popular every day, I really want to get into this world and be a buff later in this field.

    Through studying information on the web in the past weeks, I have been confused and overwhelmed by an avalanche of ideas of coding, programming, setting, different output/data formats, many introductions of commercial XML editor/author tools which support DITA. It appears that learning DITA and XML authoring/editing is extremely hard, isn’t it?

    I am currently working for a local company as a technical writer. My works can be easily handled by using MS word, Visio, Acrobat and sometimes photoshop. However, I am eager to extend my professional skills in this field so that I can have better chances in career development.

    I have been reading Introduction to DITA by Hackos and DITA Best Practices for several days and following your walking through and by support from a friend, I have built the DITA OT on my laptop.

    Well, the DITA OT really kills me because I know nothing about coding and programming. I even don’t know how to finish “The World’s Smallest DITA Project” on your blog.
    Different DITA OT versions have different commands for delivering the same output format, it confuses me, not even mentioning to analyze then resolve the error message/prompt after I deliver a command but can’t get what is expected. So I am planning to purchase a commercial XML authoring/editing tool and leave those trouble of transforming to different output formats to the software and machine, not me to deal with the transformation. Am I doing right?

    Pardon me for this tangled email. Could you suggest what I should do to get into this field and get bigger effectively? I shall be very obliged to you if you could make a few suggestions.
    Thank you very much.

    • Nathalie says:

      Hi Peter,

      Sorry for taking so long to reply. I usually get noticed when a new comment is posted on my blog, but for some reason the notice went to my junk mail. I apologize for the delay.

      It is true that the DITA-OT can be overwhelming, especially when you’re getting started with DITA. You should know that most DITA writers are usually not involved with the DITA-OT itself. Handling the Open Toolkit (setting the templates, creating the transformation scenarios, etc.) is usually handled by a “toolsmith” or even by IT. In this project, because I wanted to use open source tools only, the steps require some advanced technical knowledge on your end. But most commercial tools, such as oXygen, handle the DITA-OT behind the scenes, so you don’t have to worry about that. You can concentrate on learning DITA, and the tool will generate the output for you. So this might be a good solution if you are willing to invest in such a tool (and many of these tools provide a free trial license).

      You do not need to become a DITA expert to get a job in this field. I had some basic DITA knowledge when I got my first DITA job, but I had no idea how the DITA-OT worked :) I developed that knowledge on the job.

      Good luck in your training and keep me posted!

  4. Kirthika says:

    Hi Nathalie,

    I’m a Technical Writer and this is the first time, I’m going work XML based tool.

    Recently, I got job and I need to work in X-metal.I have basic knowledge of the tool but what if I get a situation where I have to create tags and editing existing tag?

    I want to know about managing image in X-metal. Because sometimes, the image appears without color like for example the warning image. It shows the yellow color inside the tool but not in Final PDF. What would be the problem.

    I do not know coding and all. Could you please guide me.

    Thanks in advance

Leave a Reply

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