Edit online

Getting Started with DITA

The information in this topic is meant to be a very basic starting point for those who are just getting started using DITA in Oxygen XML Editor. Oxygen XML Editor makes it easy to create, edit, manage, and publish DITA content, but it requires at least some basic DITA knowledge. To truly get the most out of Oxygen XML Editor and all of its DITA-related features, you should explore resources in the online DITA community to acquire knowledge of its concepts and uses.

Understanding DITA Topics

It is important to understand the role that a DITA topic plays in a DITA project. A DITA topic is not associated with a single published document. It is a separate entity that can potentially be included in many different books, help systems, or websites. Therefore, when you write a DITA topic you are not writing a book, a help system, or a website. You are writing an individual piece of content. This affects how you approach the writing task and how Oxygen XML Editor works to support you as you write.

Most of your topics are actually related to other topics, and those relationships can affect how you write and handle things such as links and content reuse. Oxygen XML Editor helps you manage those relationships. Depending on how your topics are related, you can use the tools provided in Oxygen XML Editor, along with the features of DITA, in a variety of ways.

Creating a DITA Topic in Oxygen XML Editor

To create a DITA topic:

  1. Select File > New or click the New button on the toolbar.

    Step Result: The New Document Wizard is displayed:

    Figure 1. New DITA Document Wizard

  2. Go to Framework templates > DITA > topic and select the type of topic that you want to create.
    Note: If your organization has created DITA customizations, the appropriate template files may be in another location, and various types of topics may be provided for your use. Check with the person who manages your DITA system to see if you should be using templates from another directory.
  3. Select a file path where it will be saved. You can also optionally specify a title.
  4. Click Create.

Result: Your document is opened in the editor. Eventually, you will need to add a reference to it in your DITA map.

Your DITA topic is an XML document, thus all the editing features that Oxygen XML Editor provides for editing XML documents also apply to DITA topics. Oxygen XML Editor also provides additional specific DITA-related support for working with DITA topics, their associated DITA maps, and for creating DITA output.

Role of Maps

The basic method that DITA uses to express the relationship between topics is through a DITA map. Other relationships between topics, such as cross references, generally need to be made between topics in the same root map. DITA uses maps to determine which topics are part of any output that you create. While customized DITA solutions can use other mechanisms, generally DITA is not used as a way to publish individual topics. Output is created from a map and includes all the topics referenced by the map.

A publication is not always represented by a single map. For instance, if you are writing a book, you might use a submap to create each chapter and then organize the chapters in a main root map to create the book. This helps you to manage your content, offers the possibility of reusing submaps, and segregates content to support multiple people working on the same project.

Creating a Map in Oxygen XML Editor

To create a map:
  1. Select File > New or click the New button on the toolbar.
  2. Go to Framework templates > DITA Map > map and select the type of map you want to create.

  3. Choose whether you want to open the map in the Editor or in the DITA Maps Manager. Usually, opening it in the DITA Maps Manager is the best choice. The DITA Maps Manager presents a view of the DITA map that is similar to a table of contents.

    Figure 2. DITA Maps Manager View

Adding Existing Topics to a Map in Oxygen XML Editor

There are several ways to add a topic reference to a map. Perhaps the easiest method is to add a reference to a topic that is already open in the editor:
  1. Open the DITA topic in the main editing window.

  2. Right-click the DITA map in the DITA Maps Manager view and choose Reference to the currently edited file from the Append Child, Insert Before, or Insert After submenu.

    Step Result: This opens the Insert Reference dialog box with all of the required fields already filled in for you.

    Figure 3. Insert Reference Dialog Box

  3. You can fill in additional information in the various tabs in this dialog box or add it to the map later.
  4. Select Insert and close to add a reference to your topic in the map.
  5. Save the DITA map.

Adding New Topics to a Map in Oxygen XML Editor

As you add topics to your map, you may want to create a new topic as a child or sibling of another topic. This is usually done at the map level.

To add a new topic to a map, follow these steps:
  1. In the DITA Maps Manager, right-click the node in the current map where you want to add the new topic.
  2. Select one of the following actions:
    • Append Child > New - Select this action to insert the new topic as a child of the selected node. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
    • Insert Before > New - Select this action to insert the new topic as a sibling to the current node, before it. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
    • Insert After > New - Select this action to insert the new topic as a sibling to the current node, after it. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
    • Duplicate - Select this action to create a copy of the selected topic and insert it as a sibling. This action opens a dialog box that allows you to choose the file name and location for the newly created copy of the topic. After you have selected the name and path for your new topic, click OK.
      Note: The value of the root ID is generated taking the Use the file name as the value of the root ID attribute option from the DITA > Topics preferences page into account. When the option is deselected, a unique ID is generated.

    Step Result: The new topic is now referenced (as a <topicref>) in the DITA map at the location where you inserted it and the new topic is opened in the editor.

  3. Save the DITA map.
You can also change the order and nesting of topics in the DITA Maps Manager view by doing either of the following:
  • Select the topic to move while holding down the Alt key and use the arrow keys to move it around.
  • Use the mouse to drag and drop the topic to the desired location.

The way your parent and child topics are organized in any particular output depends on both the configuration of those topics in the map and the rules of the output transformation that is applied to them. Do not assume that your topics must have the same organization for all output types. The map defines the organization of the topics, not the topics themselves. It is possible to create a variety of maps, each with different organization and configuration options to produce a variety of outputs.

Adding Submaps in Oxygen XML Editor

If you have a large set of information, such as a long book or extensive help system, a single map can become long and difficult to manage. To make it easier to manage, you can break up the content into smaller submaps. A submap might represent a chapter of a book, a section of a user manual, or a page on a website. To build a publication out of these smaller maps, you must add them to a map that represents the overall publication.

To add a child map to the current map:

  1. Right-click the parent DITA map in the DITA Maps Manager view and choose Append child > Map reference.

    Step Result: This opens the Insert Reference dialog box with all of the required fields already filled in for you.

  2. You can fill in additional information in the various tabs in this dialog box or add it to the map later.
  3. Select Insert and close to add a reference to your submap in the main map.
  4. Save the main DITA map.

Validating a Map in Oxygen XML Editor

Just as it is with your individual topics, it is important to validate your maps. Oxygen XML Editor provides a validation function for DITA maps that does more than simply validating that the XML is well-formed. It also does the following:
  • Validates all of the relationships defined in the maps.
  • Validates all of the files that are included in the map.
  • Validates all of the links that are expressed in the files.
Validating the map that describes your entire publication validates all the files that make up the publication and all of the relationships between them.
To validate a map:

  1. Click the Validate and Check for Completeness button in the DITA Maps Manager view.

    Step Result: This opens the DITA Map Completeness Check dialog box.

  2. Select any of the various options you want to check.
  3. Click Check to run the validation process.

Publishing Your Topics in Oxygen XML Editor

As noted previously, in DITA standards you usually do not publish output from an individual topic. Instead, you create published output by running a DITA transformation on a map. This collects all the topics that are referenced in the map, organizes them, and produces output in a particular format. By default, Oxygen XML Editor uses the transformations provided by the DITA Open Toolkit for publishing to various output formats (such as PDF, WebHelp or EPUB). Your organization may have created various custom transformations or modified the built-in DITA Open Toolkit transformations. In either case, Oxygen XML Editor manages them by using transformation scenarios.

To publish output for a map:

  1. Click the Configure Transformation Scenario(s) button in the DITA Maps Manager view.

    Step Result: This opens the Configure Transformation Scenario(s) dialog box.

    Figure 4. Configure Transformation Scenarios Dialog Box
  2. Select the appropriate transformation depending on the type of output you desire.
  3. To change or view the configuration or storage options for a transformation scenario, select the transformation and click Edit.

  4. Click Apply associated.

Result: Depending on the configuration of the transformation scenario, when the transformation is finished, your output may automatically be opened in the appropriate application.

DITA Projects

Once you have a basic understanding of DITA and how to work with DITA topics and maps, you probably want to create a DITA project to organize and manage your planned content/resources. Oxygen XML Editor includes a Project view that helps you organize your projects and offers a variety of helpful project-related features and makes it easy to share your projects with other members of your team.
Tip: There are several sample project templates available for DITA users that can be used as a starting point or for inspiration. These sample project templates are found in the Framework templates > DITA folder in the New Project wizard:
  • Sample DITA Project - This is a basic DITA project meant to help new users see how a DITA project is structured.
  • Startup DITA Project - This is a startup DITA project that imposes a custom set of options (e.g. spell check settings and custom dictionaries), a custom DITA framework extension (e.g. custom new file templates. custom actions, custom CSS used for visual editing) and a folder structure for a DITA project according to best practices. Once created, the project contains a Readme.html file that explains all customizations and their benefits. If you plan to start your own DITA project using a version control system (such as Git), you can use this startup DITA project template to customize various aspects of DITA editing and share them with your team.

Resources

For more information about getting started with DITA and how to work with DITA in Oxygen XML Editor, see our compiled collection of DITA-related webinars that are meant to help you with your journey into working with DITA: Webinars: Working with DITA in Oxygen.