Unlock the Power of DITA in AsciiDoc with adoc Studio

What is DITA?

Darwin Information Typing Architecture, commonly known as DITA, is a framework designed for modular, structured writing.

DITA organizes content into reusable components called topics:

• Concepts: Explain what something is.

• Tasks: Provide step-by-step instructions.

• References: Present structured information like tables or specifications.

These topics are tied together using a DITA Map, defining the document's hierarchy and relationships. It’s a system tailor-made for technical writers who need to manage complexity.

XML versus AsciiDoc

While DITA uses XML, which can feel overwhelming with its verbosity, AsciiDoc offers a cleaner, more human-readable syntax. adoc Studio allows you to write in AsciiDoc while keeping the structured logic of DITA.

Here’s why AsciiDoc in adoc Studio outshines XML for DITA-like projects:

1. Readable Yet Powerful: Unlike XML's verbose syntax, AsciiDoc is clean and intuitive, while still supporting essential elements like tables and quotes—no extensions or additional tools required.

2. Built-In Assistance: XML demands strict formatting and constant reference to schemas. In contrast, adoc Studio’s adoc Coach guides you with real-time syntax support, reducing errors and speeding up your workflow.

3. Instant Previews: With XML, you often rely on external converters and tedious back-and-forth to preview content. adoc Studio provides dynamic HTML and PDF preview and export directly, removing the need for external processing.

Here’s a comparison that highlights the verbosity of XML versus the simplicity of AsciiDoc when creating a table—a common syntax element in structured documents:

In XML: 483 characters

<table>
  <title>Comparison Table</title>
  <tgroup cols="3">
    <thead>
      <row>
        <entry>Feature</entry>
        <entry>AsciiDoc</entry>
        <entry>XML</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Syntax</entry>
        <entry>Simple</entry>
        <entry>Verbose</entry>
      </row>
      <row>
        <entry>Flexibility</entry>
        <entry>High</entry>
        <entry>Moderate</entry>
      </row>
    </tbody>
  </tgroup>
</table>

In AsciiDoc: 105 characters

.Comparison Table
|===
|Feature |AsciiDoc |XML
|Syntax |Simple |Verbose
|Flexibility |High |Moderate
|===

How to Set Up a DITA-Like Project in adoc Studio

Now, let's create an example project following the DITA structure in adoc Studio.

1. Create a standardized File Structure

First of all, we want to create a modular file structure that can be scaled to include further customers along the way. For this, we need three components:

1. Customer Components: An Individual folder for each client.

   • Example Files for each Customer: customer-details.adoc & contract-specifications.adoc

2. Global Components: Centralized folder for all files that are used across multiple projects.

   • Example Files: about-us.adoc & terms.adoc

3. Project Map: Combines global and customer-specific components dynamically. For this example, we'll call it Contracts.ads

This leaves us with this document structure:

Documents/
├── Contracts.ads/
│   ├── Contract.adocproject/
│   ├── local-file.adoc/
│   ├── Media/
│   ├── project-map.adoc/
├── Customers/
│   ├── adoc Studio/
│   │   ├── customer_details.adoc
│   │   ├── contract-specifications.adoc
│   │   ├── ...
│   ├── Customer_A/
│   │   ├── customer_details.adoc
│   │   ├── ...
│   ├── Customer_B/
│   │   ├── customer_details.adoc
│   │   ├── ...
├── Global Components/
│   ├── about-us.adoc
│   ├── terms.adoc
│   ├── ...

2. Create the Project Map

The Project Map acts as the central hub for your documentation, combining global and customer-specific components. Think of it as the equivalent of a DITA Map.

In adoc Studio, we’ll create a new project called contract.adocprojectand use the include::[] directive to integrate files seamlessly.

Internal Internal Files

Files stored within the same directory as your project can be included directly by referencing their file name. This keeps everything self-contained and easy to manage.

Tip: Use adoc Studio’s adoc Coach for real-time guidance on setting up the include::[] syntax correctly. Simply press the ESC key or type the first few letters of the syntax incl and the Coach will automatically open to suggest the correct syntax.

adoc Studio

Create Technical Documentation in AsciiDoc.
Organize, Write and Share.
Documentation in AsciiDoc.
Organize, Write and Share.

Start Free 14-Day Trial

Including External Files via Relative Paths

For files located outside the project directory, use relative paths. This method ensures modularity and reusability of shared content.

• ../: Moves up one directory level.

• Additional ../: Each additional ../ moves one more level up the directory tree.

• After navigating up, specify the folder and file you want to include.

This approach is perfect for including global components like terms or company information, ensuring consistency across multiple projects.

Including External Files via Absolute Paths

If needed, you can use absolute paths to reference files. This method starts from the root directory (e.g., file:/absolute/path/to/file.adoc). Absolute paths are robust and reduce dependency on project structure but may be less portable.

Dynamic Customer-Specific Files

Dynamically include customer-specific files by defining an attribute such as :customer: in your Project Map and add the reference {customer} to your file path within the include directive.

Then, update the attribute to switch between clients easily.

3. Excursus: Set Conditions to Embed or Exclude Information

Conditional text and attributes let you tailor your documents to specific audiences, creating flexible outputs without duplicating files.

For example, if you maintain internal comments for each customer in files like internal-comments-adoc-studio.adoc, you can include them in internal exports for your team. The correct commentary is dynamically embedded for each export by using an attribute for the customer name.

Use attributes like :internal: in your product to toggle visibility dynamically.

With these export options, adoc Studio ensures you can handle any documentation challenge, whether it’s a one-off client request or a batch of customized outputs.

:customer: adoc Studio
:internal:

ifdef::internal[]
include::internal-comments-{customer}.adoc
endif::[]

4. Export your Project

Now that we've set up a project map and included attributes and conditions, we can create an initial export of the new contract.

For this, there are two ways: either export the file directly, or set up a product to store export settings such as attributes for repurposing.

Ready to Transform Your Workflow?

Start building DITA-like modular documentation with AsciiDoc in adoc Studio. Combine simplicity, flexibility, and power in one tool. Sign up for a 14-day free trial and experience seamless documentation creation today.