8.3 DITA 主题类型

DITA（Darwin Information Typing Architecture）是一种基于 XML 的文档架构标准，通过主题类型化实现内容的结构化管理。

R-146 必须

DITA 文档必须使用正确的主题类型

使用 DITA 编写技术文档时，必须根据内容性质选择正确的主题类型：概念（concept）用于解释性内容，任务（task）用于操作步骤，参考（reference）用于查阅性信息。混用主题类型会破坏内容的结构化特性，降低复用性和可维护性。

DITA 三种主题类型

主题类型	英文名	用途	典型内容
概念	concept	解释概念、原理和背景知识	产品简介、功能概述、术语解释、架构说明
任务	task	引导用户完成具体操作	安装步骤、配置流程、操作指南、故障排除
参考	reference	提供查阅性的技术细节	API 参数表、配置项列表、错误码、命令语法

DITA concept 主题示例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="what_is_api">
  <title>什么是 API</title>
  <shortdesc>API（应用程序编程接口）是软件系统之间通信的桥梁。</shortdesc>
  <conbody>
    <p>API 定义了软件组件之间交互的规范，使不同系统能够交换数据和功能。</p>
    <section>
      <title>API 的类型</title>
      <ul>
        <li>REST API：基于 HTTP 协议的轻量级接口</li>
        <li>SOAP API：基于 XML 的结构化接口</li>
        <li>GraphQL：灵活的查询语言接口</li>
      </ul>
    </section>
  </conbody>
</concept>

DITA task 主题示例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="create_api_key">
  <title>创建 API 密钥</title>
  <shortdesc>通过管理控制台创建用于身份验证的 API 密钥。</shortdesc>
  <taskbody>
    <prereq>您需要拥有管理员权限。</prereq>
    <steps>
      <step><cmd>登录管理控制台。</cmd></step>
      <step><cmd>在左侧导航栏中选择「API 管理」。</cmd></step>
      <step><cmd>单击「创建密钥」按钮。</cmd></step>
      <step><cmd>输入密钥名称和描述。</cmd></step>
      <step><cmd>单击「确认」完成创建。</cmd></step>
    </steps>
    <result>系统将生成一个新的 API 密钥并显示在列表中。</result>
  </taskbody>
</task>

DITA map 的作用是什么？

DITA map 是一种用于组织和管理 DITA 主题的容器文件。它定义了主题之间的层级关系和引用关系，类似于书籍的目录。

DITA map 的主要作用包括：

定义文档的整体结构和章节顺序
通过 topicref 元素引用各个主题文件
支持条件过滤，根据不同受众生成不同版本的文档
管理主题之间的关系表（relationship table）
指定输出格式和发布参数

什么时候使用 reference 主题？

reference（参考）主题适用于以下场景：

API 接口的参数说明和返回值描述
配置文件的参数列表和取值范围
命令行工具的语法和选项说明
错误码和状态码对照表
产品规格和技术参数表

reference 主题的特点是内容以表格和定义列表为主，用户通常不会从头到尾阅读，而是按需查阅特定条目。因此，reference 主题应提供清晰的分类和索引，方便用户快速定位所需信息。