Home » How to Use Oxygen XML Editor for DITA Authoring

DITA getting started

How to Use Oxygen XML Editor for DITA Authoring

By Harry Longmuir

July 10, 2025
12:37 pm

Create topicsValidate the mapPublish and review

To start authoring DITA in Oxygen XML Editor, create a topic from a suitable template, organize it in a DITA map, validate the complete publication, and run a transformation to generate output. That small end-to-end exercise teaches more than exploring every toolbar before writing anything.

This seven-step guide follows Oxygen XML Editor 28.1 documentation. Your organization may provide customized templates, menus, validation rules, or publishing scenarios, so use its approved configuration when one exists. The example goal is a small installation guide containing a concept, a task, and a reference topic.

Step 1: Prepare Oxygen and a small working folder

Install the organization-approved version of Oxygen XML Editor from the official Oxygen website. Confirm which product and license your team uses before installing a different edition. Oxygen XML Author also supports structured authoring; XML Editor includes additional XML development tools. A CCMS deployment may supply its own integration and setup instructions.

Create a folder for this exercise with space for topics, images, and generated output. Keep source files separate from output files so it is clear which files you should edit. If your team uses a repository, follow its naming and storage conventions from the beginning.

Why this matters: DITA files refer to other resources. A predictable folder structure makes those references easier to manage and reduces accidental dependence on files elsewhere on your machine.

Check before continuing: Open Oxygen successfully, confirm that the DITA templates are available, and ask your administrator whether you should use a custom framework. If an existing XDocs environment is involved, use its approved connection rather than creating an unmanaged duplicate of production content.

Step 2: Create your first DITA topic

Use File > New and find the DITA topic templates under Framework templates. Choose a concept for an explanation such as “Before you install,” then supply a meaningful filename, location, and title. Create the file and save it in your working folder.

Oxygen’s topic-creation documentation also explains creating topics from an existing map. For this first exercise, creating a topic separately makes the distinction between the information and its publication easier to see.

Choose the information type deliberately. Use a task for instructions a reader follows, a concept for an explanation, and a reference for lookup information. Do not put the entire manual into one topic simply because the template allows you to add more content.

Check before continuing: Confirm that the file has a title and topic identifier, that it is saved where expected, and that the selected template matches the kind of information you plan to write. A template gives you a starting structure; your edits still need validation.

Step 3: Write the content in Author mode

Author mode presents XML in a readable editing view. It is useful for writing without constantly handling source markup, but its appearance is an authoring presentation rather than a guarantee of the final PDF or web layout. Text mode lets you inspect the underlying XML when needed.

Write a short explanation in the concept topic. Then create a task called “Install the sample application” and a reference topic for its configuration settings. Keep the exercise small enough to inspect completely.

Give each topic a specific, reader-oriented title.
Use paragraphs for explanation and the appropriate task structures for instructions.
Put the action for a step in its command element and supporting detail in the permitted supporting elements.
Use content completion or the insertion controls to choose valid elements at the current position.
Add prerequisites, expected results, or warnings when the procedure actually requires them.

Why this matters: A list that looks like a procedure is not necessarily structured as one. Semantic elements help validation and publishing tools understand the role of the content.

Check before continuing: Read the task as a user would. Can someone tell when to use it, what to do, and whether it worked? XML validation cannot establish those things for you.

Step 4: Create a map and add the topics

Create another new file, this time using a DITA Map template. Open it in DITA Maps Manager and save it with a meaningful name. Follow Oxygen’s map-creation instructions if your installation presents different choices.

To reference an already open topic, right-click the map in DITA Maps Manager and use the appropriate insertion menu to add a reference to the currently edited file. Review the reference dialog and insert it. Repeat for your other topics, then arrange them in the intended order and save the map.

The map organizes the publication. It does not require you to copy all the topic text into one file. For a larger publication, submaps can help organize groups of topics, but one simple map is enough for this exercise.

Check before continuing: Open each topic from the map and confirm that the expected file appears. Check the order and nesting. If a topic is missing, first distinguish a missing reference from a topic that was never saved.

Step 5: Validate topics and check the complete map

Validate individual topics while you work, then run the publication-level check. Select the root map in DITA Maps Manager, confirm the context points to that map, and refresh it. Use Validate and Check for Completeness, select the checks appropriate to your project, and run the check.

The map validation and completeness documentation explains the available options. Publication validation can inspect referenced topics and maps and identify broken resource paths. If you use profiling, validate the intended filtered configurations as well.

Work through the reported issues in context. An invalid element order requires a structural correction. A missing image may require a corrected path or an added resource. An unresolved key may mean the wrong root-map context is active. Do not delete a useful check just to make the warning disappear.

Check before continuing: Resolve errors and review remaining warnings deliberately. Then inspect technical accuracy, terminology, links, and required content with a human reviewer. A valid publication can still contain an incorrect instruction.

Step 6: Generate and inspect the output

Select the map and open Configure Transformation Scenario(s) from DITA Maps Manager. Choose a suitable supplied or organization-approved scenario, inspect its settings and output location, and apply the associated transformation. Oxygen’s DITA publishing documentation describes the publishing workflow.

Start with one output format, then test a second if it is part of your requirements. DITA-OT and configured publishing tools can generate formats such as HTML and PDF; the exact scenarios, extensions, and licensing depend on your installation. WebHelp output and a complete documentation delivery portal are related but different parts of a solution.

Open the generated result and inspect every topic in this small exercise. Follow links, check images and tables, and review the navigation. For PDF, inspect page breaks, running text, and any clipped content. For web output, check the experience at relevant screen sizes and include accessibility testing in your normal release process.

Check before continuing: Confirm that you built the intended map with the intended profile. If the build fails, read the transformation messages before retrying. If it succeeds but content is missing, inspect the map and filtering configuration rather than editing the generated files.

Step 7: Put the source under an agreed team workflow

A successful local exercise is a starting point. Before adding production content, decide where the authoritative source lives, who can change it, how review works, and how releases are recorded.

A repository-based workflow may be appropriate for some teams. A DITA CCMS such as XDocs can add coordinated management of reusable components, metadata, reviews, releases, and localization. Follow the configured integration workflow rather than assuming that a standalone editor supplies all of those controls.

Check before continuing: Have a second authorized team member open the content, review a change, and reproduce the output using the agreed setup. Confirm that required images, schemas, and publishing resources are available to them. A workflow that only works on the first author’s computer is not ready to scale.

Frequently asked questions

Is a DITA project the same as a DITA map?

No. The map organizes referenced content for a publication. An Oxygen project helps organize working resources and configuration. You can create a topic and map before setting up a broader project; Oxygen’s getting-started guide introduces that progression.

Why does a topic validate but the map still report errors?

The topic may have valid XML structure while its publication has missing resources, unresolved references, or other relationship problems. Check the root-map context and the specific completeness messages.

Why is content missing from the output?

Check that the topic is referenced by the map you transformed. Then inspect profiling filters, conditional attributes, and the chosen scenario. Confirm you are viewing the latest output rather than an older build.

Do I need a CCMS to learn DITA in Oxygen?

No. A small local project is sufficient for learning topics, maps, validation, and publishing. Introduce team management based on your real collaboration, reuse, release, and localization requirements.

Contact Us

IN THIS ARTICLE

01Step 1: Prepare Oxygen and a small working folder
02Step 2: Create your first DITA topic
03Step 3: Write the content in Author mode
04Step 4: Create a map and add the topics
05Step 5: Validate topics and check the complete map
06Step 6: Generate and inspect the output
07Step 7: Put the source under an agreed team workflow
08Frequently asked questions

SOURCE LINKS