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

The World’s Smallest DITA Project Part 2: Let’s do it!

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

Now that you’ve installed and tested the tools, the fun can begin :)

The World’s Smallest DITA Project is a simple map that will contain a single topic. The objective of today’s exercise is not to cover all the DITA concepts but rather to go through a complete cycle of creating a DITA topic, adding it to a DITA map, and converting the DITA map to a PDF file.

The project will be stored in a directory called Worlds_smallest_dita_project.

Create a topic


First, let’s create a topic. As we’ve seen, there are three types of topics: concept, task, and reference. For this project, we’ll create a topic of type concept.

To create a topic:

  1. Using Windows Explorer, create the directory that will contain your project, directly under the C:\ directory, and name it Worlds_smallest_dita_project.
  2. Start Notepad++.
  3. Select File–>New.
  4. Select File–>Save As.
  5. Navigate to the C:\Worlds_smallest_dita_project directory and save the file as wsdp_small_is_beautiful.xml.
  6. Copy the following header to the wsdp_small_is_beautiful.xml document:
    <!--?xml version="1.0" encoding="utf-8"?-->
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\concept.dtd">
    

    The first line specifies that this is an XML document. The second and third lines indicate that this document is of type concept and should be validated against the concept.dtd DTD file. A DTD file can be seen as the dictionary that defines how a DITA document can be formed.

    As you can see in the example above, the third line provides an absolute path to the concept.dtd file that is packaged with the DITA OT. In a real project, you would not provide the absolute path to the DTD, as we’re doing here, since you want to be able to move your project files. You would instead declare a public ID in an XML catalog that basically says: “When I talk about the concept.dtd file, here’s where to find it”. But to keep this project easy (it is, after all, the World’s Smallest DITA Project), we’ll include an absolute path.

  7. Edit the third line so that it points to the concept.dtd file provided with your DITA OT.
    For example, if you installed the DITA OT in the C:\DITA-OT1.8 directory, change the third line to the following:

    <!--?xml version="1.0" encoding="utf-8"?-->
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8\dtd\technicalContent\dtd\concept.dtd">
    
  8. Add the following line at the end of the file:
    <concept id="wsdp_topic_1" xml:lang="en-us">
    

    The <concept> element is the top-level element of a topic of type concept. In the example above, we specify an ID for this topic (“wsdp_topic_1”) so that we can create cross-references to it. We also specify that it’s written in US English.

  9. Specify the title of the document by adding the following line at the end of the file:
       <title>Small is beautiful</title>
    
  10. Specify a short description for this topic by adding the following lines:
    <shortdesc><i>Small is beautiful</i> is the title of a book written
        by Ernst Friedrich "Fritz" Schumacher.</shortdesc>
    

    A <shortdesc> is a special DITA element used to provide a short description of the topic. The short description is a very interesting element that can also be used to preview the content of a link or for searching when the document is generated.

  11. Finally, add the following line to close the <concept> element:
    </concept>
    

    The file should now look as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\concept.dtd">
    <concept id="wsdp_topic_1" xml:lang="en-us">
       <title>Small is beautiful</title>
       <shortdesc><i>Small is beautiful</i> is the title of a book written
           by Ernst Friedrich "Fritz" Schumacher.</shortdesc>
    </concept>
    
  12. Select  File–>Save.

Now let’s create a DITA map.

Create a map


To create a map:

  1. In Notepad++, select File–>New.
  2. Select  File–>Save As.
  3. Navigate to the C:\Worlds_smallest_dita_project directory and save the file as worlds_smallest_dita_project.ditamap‏.
    Note: Make sure that there is no extra space after the file name before you click Save.
  4. Copy the following header to the worlds_smallest_dita_project.ditamap‏ document:
    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\map.dtd">
    

    As with the topic file, the first line specifies that this is an XML document. The second and third lines indicate that this document is of type map and should be validated against the map.dtd DTD file.

  5. Edit the third line so that it points to the map.dtd file provided with your DITA OT.
    For example, if you installed the DITA OT in the C:\DITA-OT1.8 directory, change the third line to the following:

    <!--?xml version="1.0" encoding="utf-8"?-->
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
     "C:\DITA-OT1.8\dtd\technicalContent\dtd\map.dtd">
    
  6. Add the following line at the end of the file:
    <map title="World's Smallest DITA Project">
    

    The <map> element is the top-level element of a map. In the example above, we also specify the title of the map in the title attribute of the map element.

  7. Add a reference to the topic “Small is beautiful” by adding the following line:
    <topicref href="wsdp_small_is_beautiful.xml" type="concept"/>
    

    This element indicates that the wsdp_small_is_beautiful.xml file is now included in the map.

  8. Finally, add the following line to close the <map> element:
    </map>
    

    The file should now look as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
     "C:\DITA-OT1.8.M2\dtd\technicalContent\dtd\map.dtd">
    
    <map title="World's Smallest DITA Project">
       <topicref href="wsdp_small_is_beautiful.xml" type="concept"/>
    </map>
    
  9. Select  File–>Save.

Now let’s generate some PDF!

Generate the World’s Smallest DITA Project to PDF


  1. In the directory where you installed the DITA OT (for example, C:\DITA-OT1.8.M2), double-click startcmd.bat (Windows) or run startcmd.sh (Linux, Mac).
  2. At the prompt, enter the following command:
    ant -f build_demo.xml

    The following message is displayed:

    [echo] Please enter the filename for the DITA map that you
    [echo] want to build including the directory path (if any).
    [echo] The filename must have the .ditamap extension.
    [echo] Note that relative paths that climb (..) are not supported yet.
    [echo] To build the sample, press return without entering anything.
    [input] The DITA map filename: [C:\DITA-OT1.6.M5\samples\hierarchy.ditamap]
  3. Type C:\Worlds_smallest_dita_project\worlds_smallest_dita_project.ditamap and press Enter.
    The following message is displayed:

     [echo]
     [echo] Please enter the name of the output directory or press return
     [echo] to accept the default.
     [input] The output directory (out): [out]
  4. Type C:\Worlds_smallest_dita_project\out and press Enter.
    This will create an out directory in the C:\Worlds_smallest_dita_project\ project directory.
    The following message is displayed:

     [echo] Please enter the type of output to generate.
     [echo] Options include: eclipse, tocjs, htmlhelp, javahelp, pdf, or web
     [echo] Use lowercase letters.
     [echo]
     [input] The output type: (eclipse, tocjs, htmlhelp, javahelp, pdf, [web], docbook)
  5. Type pdf and press Enter.
    The following message is displayed:

     [echo] Ready to build C:\Worlds_smallest_dita_project\worlds_smallest_dita_project.ditamap
     [echo] for PDF in C:\Worlds_smallest_dita_project\out
     [echo]
     [input] Continue? (Y, [y], N, n)
  6. Press Enter.
    The DITA OT converts the DITA map to PDF. After a few minutes, the following message is displayed:

    BUILD SUCCESSFUL
    Total time: 2 minutes 54 seconds

    Note: If you do not get this message, see Troubleshooting below

And… voilà! To look at your newly generated output, double-click the worlds_smallest_dita_project.pdf file in the following directory:
C:\Worlds_smallest_dita_project\out

What’s Next?


Now that you’ve created your first DITA project, you might try a few things:

  • Generate the file in html (hint: select the “web” option)
  • Add more text to your topic
  • Create another topic and add it to the map

The objective of this exercise was to take you through the whole process of creating a project in DITA and generating an output, using open-source tools. Now that you’re able to create a small project, you can build on this to learn DITA. The next step will be to plan your training, which will be the subject of the next post. Learning a new technology is like training for a race. I’m a runner, and I know that if I want to achieve a race goal (running a 10K, improving my race time), I need to plan my training week by week. If learning DITA on your own is your goal, then you also need a training plan.

Until the next post, be safe and have fun!

Troubleshooting


If you get an error message when generating your PDF file:

  1. Make sure that you can generate a PDF using the DITA OT sample project as described in the post on installing the tools. If you can generate the demo PDF but not the World’s Smallest DITA Project, then you know that the problem is with your code. Otherwise, the problem is with the DITA OT installation.
  2. Check that you are pointing to the right DTDs in the third line of your files.
  3. Make sure that the contents of your DITA files match the examples above.

If you still can’t figure out the issue, describe the problem in the comments section and I’ll try to help you figure it out.


The World’s Smallest DITA Project Part 1: Installing the tools

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

Before you can start having fun with DITA, you need to install the following tools:

  • A DITA editor
  • The DITA Open Toolkit

You use a DITA editor to write your topics, create your maps, and add your topics to maps. To generate your DITA content into the output format of your choice (PDF, .chm, HTML, etc.), you use the DITA Open Toolkit publishing engine, as shown in the following diagram:

DITA editor


An ideal DITA editor has the following features:

  • It includes a visual interface that lets you enter content without having to worry about tags. While it’s very useful to understand the DITA tags and be able to work with them, you don’t want to worry about the mechanics when you are writing your content.
  • It also includes a text interface that lets you work in the DITA code. This is very useful when you perform more complex operations such as applying conditions, adding cross-references, setting variables, etc. I work in the visual interface about 80% of the time and in the text interface 20% of the time.
  • It checks the syntax of your DITA code. Even when you’re working in a visual interface that does most of the job for you, you may still make mistakes. A good DITA editor will check your syntax as you type and will let you know when you make mistakes.

I’ve spent a few hours searching for a free XML editor that provides these features, but none seems available (and if I’m wrong, please, please let me know!). Many products provide a 30-day free trial, such as oXygen (which I use and love), and I’ll discuss this option when planning your DITA training.

For the World’s Smallest DITA Project, we will use Notepad++. It’s free, easy to use, and will work fine for what we want to do. Yes, when using Notepad++ you will be working with the tags, but as Sarah O’Keefe from Scriptorium said: “If you don’t understand the underlying DITA structure, you’re just going to continue to create badly structured information that is technically valid.”

Downloading and installing Notepad++

Notepad++ is a very common editor, and you may already have it installed on your computer.

If you don’t, follow these instructions:

  1. Go to the following URL:
    http://notepad-plus-plus.org/download/v6.5.2.html.
  2. Click the DOWNLOAD button.
  3. When the file is downloaded, run the installer.
  4. Follow the instructions, using the default selections.
    Note: If you get errors indicating that a file is moved to the “disable” directory, simply ignore them and click OK.
  5. When the installation is completed, click Finish.

DITA Open Toolkit


The DITA Open Toolkit (also called the DITA-OT) is an open source publishing tool that converts DITA content into various output formats such as PDF, XHTML, Eclipse Help, HTML Help, etc. To generate the output of a DITA map or topic, you run a command-line DITA-OT script that takes the map or topic as input and generates the content.

To download and install the DITA Open Toolkit:

  1. Go to the DITA Open Toolkit download website:
    http://dita-ot.github.io/download.html
  2. Click the button for your operating system.
    The file is downloaded to your system. The Open Toolkit is packaged as a .zip (Windows) or .tar.gz (Unix, Mac) file.
  3. Extract the file to the C:\ directory (Windows).
    The DITA OT is now installed in the C:\DITA-OT1.8.M2 directory.

The next step is to run the demo project provided with the DITA-OT to test your installation. To build the demo project, you run a script that asks for the DITA map that you want to build, the directory where you will store the output, and the type of output you want to create. For this test, we’ll accept the default answers to all questions.

  1. In the  C:\DITA-OT1.8.M2 directory, double-click startcmd.bat (Windows) or run startcmd.sh (Linux, Mac).
  2. At the prompt, enter the following command to build the demo project:
    ant -f build_demo.xml

    The following message is displayed:

    [echo] Please enter the filename for the DITA map that you
    [echo] want to build including the directory path (if any).
    [echo] The filename must have the .ditamap extension.
    [echo] Note that relative paths that climb (..) are not supported yet.
    [echo] To build the sample, press return without entering anything.
    [input] The DITA map filename: [C:\DITA-OT1.6.M5\samples\hierarchy.ditamap]

    Note: If you get the following error message instead:

    "java.exe"' is not recognized as an internal or external command...

    You need to update your system PATH variable with the location of your Java bin directory (for example, C:\Program Files\Java\jre7\) before you can try again. See these Java instructions for more information.

  3. Press Enter to use the default DITA map filename.
    The following message is displayed:

     [echo]
     [echo] Please enter the name of the output directory or press return
     [echo] to accept the default.
     [input] The output directory (out): [out]
  4. Press Enter to use the default output directory.
    The following message is displayed:

     [echo] Please enter the type of output to generate.
     [echo] Options include: eclipse, tocjs, htmlhelp, javahelp, pdf, or web
     [echo] Use lowercase letters.
     [echo]
     [input] The output type: (eclipse, tocjs, htmlhelp, javahelp, pdf, [web], docbook)
  5. Press Enter to generate the map to XHTML.
    The following message is displayed:

     [echo] Ready to build C:\DITA-OT1.6.M5\samples\hierarchy.ditamap
     [echo] for web in out
     [echo]
     [input] Continue? (Y, [y], N, n)
  6. Press Enter.
    The DITA OT converts the DITA map to XHTML. After a few minutes, the following message is displayed:

    BUILD SUCCESSFUL
    Total time: 2 minutes 54 seconds

    Note: If you do not get this message, see the DITA OT user documentation at the following location:
    C:\DITA-OT1.8.M2\doc\userguide.pdf

    If you can’t make this work by following the documentation, please post your error in the comments section below and I’ll try to help you fix the issue.

  7. To look at your newly generated output, double-click the index.html file in the following directory:
    C:\DITA-OT1.8.M2\out

If you want, you can run this procedure again, this time choosing a different output type.

What’s Next?


You are now ready to write your first DITA document! This will be the subject of the next post.  I will be off snowshoeing during the holidays and will come back with part 2 of the World’s Smallest DITA Project in 2014.

Until then…Happy Holidays, be safe, and be happy. :)


For the curious:

  • To lean more about the features that you need in a DITA editor, read this article from the April 2008 STC intercom issue. It’s five years old, so the list of tools is out of date, but the article still provides very useful information.
  • The DITA Writer has compiled a list of DITA optimized editors, which are XML editors best suited for producing DITA content.


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.


Learn DITA on Your Own

In a series of articles on the continuing growth in the use of DITA across the States, DITAWriter Keith Schengili-Roberts stated that “job postings seeking DITA experience continue to grow while FrameMaker usage continues to decline.” Clearly, knowing DITA can be a very important asset in a technical writer’s portfolio.

While at the STC Summit in Atlanta last spring, I met many writers who felt stuck in their careers and wanted to learn new technologies like DITA. But they couldn’t afford to take time out of their schedules to attend a two-day training course in another city and, understandably, their employers wouldn’t pay for training not applicable to their current roles.

But it is possible to learn DITA on your own, if you know where to start!

The Internet is full of resources that you can use to learn DITA independently, at a very low cost, and at your own pace. A few years ago I felt stuck in FrameMakerLand, and learning DITA made a huge difference in my career. I want to share my experience and provide fellow writers with the resources they need to get started with DITA on their own.

This is the first in a series of posts to help you learn about DITA. I plan to cover the following topics:

  • DITA 5-minute crash course
  • The World’s Smallest DITA Project: Go through the whole process of writing a topic, creating a map, and generating your output
    • 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
  • Develop your knowledge:
    • Plan your training sessions
    • Pick a project
    • Get to work!
  • Get connected: pointers to DITA blogs, user groups, influential Twitter accounts
  • Prepare a portfolio to show potential employers
    • Make source files available in GitHub
    • Make output available on a blog

The information and the tools are out there, and you can learn DITA on your own if you know where to look. I’m hoping that this series of posts will make this process easier for you!

Coming next week: a DITA 5-minute crash course


DITA and double embeddedness

I’m not a fan of webinars, since they’re usually nothing more than a glorified sales pitch. They’re presented as best practices—e.g., “How to best present information to users”—but after a few minutes it becomes obvious that the best way to present information to users is to buy the presenter’s product. Not exactly what I was looking for.

That was not the case with a series of three webinars I attended a few weeks ago, A Cognitive Design for User Assistance. Written and presented by Ray Gallon, technical communicator, instructor on Information Architecture and Content Strategy at Paris Diderot University, and author of the very interesting blog Rant of a Humanist Nerd, this presentation was by far the most stimulating I have attended.

The first webinar in the series, Users become learners, explains how we need to see our users as learners and how we must apply ideas from cognitive development theory to the design and execution of user assistance.

This blog post summarizes at a very high level what I took away from this great presentation, but I highly recommend that you listen to the recording of this presentation on Adobe’s website (see Ray’s blog for the details). It’s an hour very well invested.

The concepts: Cognition and Context

  • Users learn best when the information they need to perform a task is available as they are performing the task.

    As writers, we often think that the documentation gives meaning to the product, but it’s actually the other way around. The product gives meaning to the documentation. Without the product, a manual has no meaning. You can read the best user guide ever written on a product, but until you have worked with the software, the documentation is too abstract to be meaningful. Users learn about how to use a product by doing something and making connections.

  • Users learn best when they understand why they are performing a task. They need to know quickly if they need to perform a task. They need concepts as they are performing their tasks.

    This goes a bit against what we’ve been told in the past years: Tasks and concepts must be separated. In fact, DITA provides two different types of topics for tasks and concepts, implying that these two types of information should not be mixed. But if you don’t know why you are doing something, how can you learn to do it?

The solution: Double embeddedness

The solution is what Ray Gallon calls “double embeddedness”:

  • Embed the user assistance directly in the user interface.
  • Embed simple concepts directly into the user assistance.

We want user assistance that will:

  • Give users all the information they need and only the information they need.
  • Deliver that information when they need it, which means at the moment they have real work to do.
  • Put a sentence or two of conceptual information in context (while the user is performing the relevant task) to reinforce knowledge acquisition and integration.
  • Explain why it is interesting to perform a task, again in one or two short sentences.
  • Embed the user assistance in the UI in such a way that:
    • The user can find it immediately, without excessive searching
    • If the user doesn’t need the help, it stays out of the way

And the beauty of this approach is that DITA is the perfect vehicle to implement double embeddedness. In his presentation, Ray demonstrates a user assistance system in which:

  • When users hover over an element of the UI, a pop up is displayed with a short overview of the function. This information comes from the <shortdesc> element of a topic.
  • If a user needs more information, clicking on the question mark in the pop-up displays simple conceptual information about the function: what does it do and why should you care? This information comes from the <body> element of the topic.
  • The tool tip pull-down also contains related links to a detailed task or more conceptual information, which are provided through <related-links> elements.

Copyright: Ray Gallon.

(Image copyright: Ray Gallon. You should watch the presentation to get the full benefits of the demo)

The demo also implemented progressive disclosure, which recommends the following:

  • Initially, show users only a few of the most important options.
  • Offer a larger set of specialized options upon request, and disclose these secondary features only if a user asks for them, meaning that most users can proceed with their tasks without worrying about this added complexity.

I was so inspired by Ray Gallon’s presentation that I met with my development team yesterday to present his findings and recommend that we apply them for this new product we are working on. We spent part of the afternoon brainstorming how to best apply these principles in our product (I work with great developers!). We came up with a different DITA implementation, and I hope to present it here when we have fully implemented it.

I love my job. :)


DITA Stack Exchange site: Let’s commit!

Since I started working with DITA, my best source of information has been the dita-users Yahoo group. This is the only place on the web where I can ask questions about DITA and know that I will get a reliable answer, usually very quickly.  But Yahoo groups aren’t exactly “high tech”. They’ve been around since 1998, and their format hasn’t been updated recently. They’re not easy to search, answers are provided over multiple pages, and the layout isn’t optimal, to say the least.

So I was quite happy to see a proposal to create a dedicated DITA Q&A forum on Stack Exchange, a platform I have found very useful when looking for programming info (on Eclipse, Tomcat, etc.). This site is very well designed, the answers are often very useful (and easy to read!), and the interface offers many interesting features, such as voting on answers.

But to get launched, the site needs to reach 200 “committers”, people who commit to use the site for three months. So… please go the DITA staging area and commit!  It will only take a minute of your time. Even if you’re just curious about DITA, or getting started with it, this Q&A forum might be very useful to you in the long run.

And if you really want to commit, read this post from Anders Svensson, who came up with the initial idea.

Let’s commit!


« Previous Entries Next Entries »