企业官网建设流程全解析

结构化写作这件事，我在几个技术文档团队里来回折腾过好些年，从最早用Word排版互相传阅，到后来上Wiki做协同，再到接触DITA这套体系，中间踩过的坑和交过的学费不算少。DITA（Darwin Information Typing Architecture，达尔文信息类型化架构）这个词，很多做技术文档、产品手册、知识库的朋友应该都听过，但真正落地用起来的团队比例并不高。原因很复杂，有工具链的问题，有学习曲线的问题，也有国内生态支持的问题。这篇内容我想把DITA标准本身讲透，同时把国内目前能用的支持方案、工具选型、实操路径都摊开来说，适合正在做文档体系升级的技术写作负责人、知识管理岗、以及想了解结构化写作到底值不值得投入的一线写作者参考。

1. 先搞清楚DITA到底解决什么问题

1.1 从“文档”到“内容组件”的思维转变

传统写作的默认单位是“一篇文档”，比如一份产品手册、一份安装指南。写作者脑子里想的是章节顺序、页码、目录结构。DITA把这套逻辑彻底翻过来了，它的基本单位是“主题”（Topic），一个主题只讲一件事，比如“如何配置数据库连接”或者“错误码E1024的含义”。主题之间通过映射（Map）组织成交付物，同一批主题可以按不同顺序、不同筛选条件拼装成不同的手册。

这个转变听起来简单，实际影响非常大。我见过不少团队一开始把原有Word文档按章节机械切成主题，结果切出来的主题动辄三四千字，内部还嵌套了概念、任务、参考三种内容混在一起，这种“伪结构化”用起来比不分主题还难受。真正的DITA主题应该控制在几百字到一千字出头，一个主题只承担一个信息职责。判断标准很直接：如果这个主题的标题没法用一个明确的动宾短语概括，那大概率切错了。

1.2 DITA的三种核心信息类型

DITA标准定义了三种基础主题类型，这是整个体系的骨架：

• Concept（概念型）：解释“是什么”“为什么”，比如某个协议的原理、某个术语的定义。它回答的是理解性问题。
• Task（任务型）：描述“怎么做”，有明确的前置条件、步骤序列、预期结果。安装、配置、操作流程都属于这一类。
• Reference（参考型）：提供查阅型信息，比如参数表、命令列表、错误码对照。用户不需要从头读，而是按需检索。

这三种类型不是随便分的，背后是信息设计学里“用户带着不同目的来找内容”的基本假设。用户想知道原理时给他步骤，他会烦；用户想照着操作时给他一大段原理，他会迷路。DITA强制你在写作前先判断信息类型，这个约束看似死板，实际是保证内容质量的第一道闸门。

除了这三种，DITA还支持Topic（通用主题）作为兜底，以及通过特化（Specialization）机制派生出自定义类型。特化是DITA比较高级的能力，后面会单独说。

1.3 内容复用与多交付物输出的底层逻辑

DITA最核心的价值主张是“一次编写，多处复用”。这个复用不是简单的复制粘贴，而是基于几个机制：

Conref（内容引用）允许把一个主题里的某个元素（比如一段警告、一个参数说明）引用到另一个主题里。源内容改了，所有引用点自动更新。这解决的是同一段话在多个文档里重复维护的问题。

Keyref（键引用）更进一层，它把“引用什么”和“引用在哪里”解耦。比如产品名称、版本号、界面元素名，统一在Ditamap里定义键值，主题里只写键引用。换一个产品型号，改一处键定义，整批文档跟着变。这个机制在多产品线共用一套文档源的场景下几乎是刚需。

Filtering/Conditional Processing（条件处理）通过给元素打属性标签（比如audience=“管理员”、platform=“云端版”），在发布时按条件筛选。同一套主题，发布给管理员看时过滤掉普通用户内容，发布云端版时过滤掉本地部署内容。

Map组织与Deliverable同一批主题，通过不同的Ditamap组织，可以输出成安装手册、用户指南、在线帮助、API文档等不同交付物。输出格式上，DITA-OT（DITA Open Toolkit）支持PDF、HTML、HTML Help、Markdown、甚至Word等多种目标格式。

这套机制组合起来，理论上能做到“内容资产化”——文档不再是消耗品，而是可维护、可重组、可度量的资产。但理论归理论，实际能不能吃到这个红利，取决于内容颗粒度设计、键管理规范、以及工具链是否顺手。

2. DITA标准的技术骨架拆解

2.1 DITA的文档类型定义与Schema体系

DITA本质是一套基于XML的文档类型定义（DTD/Schema）规范。每个主题文件是一个XML文档，根元素是<topic>、<concept>、<task>或<reference>，内部元素有严格的嵌套规则。比如<task>下面必须按<title>、<shortdesc>、<taskbody>的顺序组织，<taskbody>里又有<prereq>、<steps>、<result>等结构化槽位。

这种严格性对写作者是双刃剑。好处是结构统一，机器可处理，发布样式稳定；坏处是写作时被“框”得很死，自由发挥空间小。我的经验是，对于标准化程度高的产品文档（安装、配置、API参考），这种约束是助力；对于营销文案、白皮书这类需要灵活表达的内容，DITA并不合适，别硬套。

DITA目前主流版本是1.3，OASIS标准组织维护。1.3相比1.2增加了Scoped Key、分支过滤（Branch Filtering）、以及更完善的密钥管理机制。选版本时建议直接上1.3，1.2的生态支持在逐步收缩。

2.2 Ditamap：内容组织的指挥中枢

Ditamap是DITA的“目录+装配说明书”。它不包含正文，只包含对主题的引用和层级关系定义。一个典型的Ditamap结构大致是这样：

<map> <title>某产品用户指南</title> <topicref href="intro/concept-overview.dita" navtitle="产品概述"/> <topicref href="install/task-install.dita" navtitle="安装部署"> <topicref href="install/task-prereq.dita" navtitle="环境准备"/> <topicref href="install/task-config.dita" navtitle="参数配置"/> </topicref> <topicref href="reference/ref-params.dita" navtitle="参数参考"/> </map>

Ditamap里可以嵌套Ditamap，实现模块化组织。大项目里常见做法是按产品模块拆多个子Map，顶层Map做汇总。这里有个实操细节：navtitle属性和主题内部的<title>可以不一致，前者用于导航显示（可以更短），后者用于正文标题。很多团队忽略这个区别，导致导航栏里出现一长串完整标题，体验很差。

2.3 特化机制：标准不够用时的扩展路径

DITA允许通过特化（Specialization）派生新的元素类型或主题类型。比如某个行业有特殊的“合规声明”结构，标准里没有现成元素，可以基于<note>或<section>特化出一个<compliance-statement>。

特化的价值在于：既扩展了表达能力，又保持了与标准工具链的兼容性——因为特化元素本质上还是从标准元素继承来的，DITA-OT处理时能识别其基类。但特化不是随便玩的，它需要维护自己的DTD/Schema模块，团队里得有懂XML Schema的人。我见过一些团队为了“看起来专业”盲目特化，结果工具链升级时特化模块全得重写，维护成本远超收益。建议是：标准元素能表达的就别特化，确实有行业刚性需求再考虑，而且特化层级不要太深。

2.4 DITA-OT：绕不开的发布引擎

DITA Open Toolkit是DITA内容发布的事实标准工具，开源、Java编写、命令行驱动。它负责把DITA源文件转换成PDF、HTML、Markdown等输出格式。国内团队落地DITA，DITA-OT的配置往往是第一个拦路虎。

DITA-OT的核心概念是“转换类型”（transformation type），比如pdf2输出PDF、html5输出HTML5、markdown输出Markdown。每种转换类型背后是一套XSLT样式表和Ant构建脚本。要定制输出样式（比如套用企业模板），就得改XSLT或者用插件机制扩展。

DITA-OT的插件机制值得说一下。它支持通过插件（plugin）扩展转换逻辑，比如加一个自定义的PDF封面、改页眉页脚、增加特定的输出后处理。插件用XML配置文件声明，放在指定目录下，运行dita install命令安装。这个机制比直接改核心XSLT要安全，升级时不容易冲突。

3. 国内DITA支持生态的真实面貌

3.1 工具链支持：从编辑器到发布平台

国内能直接买到的商业DITA编辑器选择不算多，主流的有几家国外厂商的产品在国内有代理或本地化版本，功能上覆盖可视化编辑、Ditamap管理、键解析、发布预览。这类工具的优势是开箱即用，写作者不需要懂XML也能上手；劣势是授权费用不低，且深度定制受限于厂商能力。

开源路线的话，XML编辑器加DITA插件是常见组合，比如基于Eclipse的编辑器配DITA插件，或者通用的XML编辑工具加载DITA的Schema做校验和补全。这条路成本低，但需要团队自己搭环境、写配置，对技术能力有要求。

发布环节，DITA-OT是绝对主力，国内一些文档平台厂商在DITA-OT基础上做了封装，提供Web化的发布管理和样式定制界面。另外，部分国内的内容管理系统开始支持DITA源文件的导入和结构化解析，但深度参差不齐，选型时需要重点验证键引用解析、条件过滤、多Map组织这些核心能力是否完整。

3.2 中文排版与本地化适配的坑

DITA标准是面向全球化的，但中文排版有自己的一套规矩，直接套用默认的PDF转换样式会出问题。我整理了几个高频坑点：

这些问题的根源在于DITA-OT默认的PDF样式（基于XSL-FO）是按西文排版习惯设计的。解决办法要么改XSLT，要么用支持中文的FO处理器并配置好字体。这块工作量不小，建议在项目初期就预留时间做样式适配，别等到内容都写完了才发现PDF出不来。

3.3 国内团队落地的典型障碍

从我和同行交流的情况看，国内团队上DITA卡壳的地方集中在几个方面：

写作习惯的惯性。一线写作者习惯了Word的所见即所得，突然换成结构化编辑器，看到一堆标签和槽位，抵触情绪很普遍。这个只能靠培训和过渡期解决，先让核心成员跑通，再逐步推广。

内容治理的缺位。DITA的复用能力依赖内容颗粒度和键管理规范，如果没人负责制定和维护这些规范，复用就会退化成复制粘贴，结构化就白做了。建议设立内容架构师角色，哪怕兼职也行。

工具链的维护成本。DITA-OT的升级、插件维护、样式定制都需要技术投入。小团队如果没有专职人员，容易陷入“能用但不好用”的状态。可以考虑用商业工具的托管服务，或者把发布环节外包给专业服务商。

与现有系统的集成。很多团队的文档要和产品系统、翻译系统、知识库打通，DITA源文件如何与这些系统交换数据，需要做接口设计。这块国内可参考的成熟方案不多，基本得自己摸索。

4. 从零落地DITA的实操路径

4.1 内容盘点与主题切分策略

动手建DITA项目之前，先做内容盘点。把现有文档按信息类型分类，标出哪些是概念说明、哪些是操作步骤、哪些是参考表格。然后按“一个主题一件事”的原则切分。

切分时有个实用技巧：先看现有文档的标题层级，二级标题往往对应一个主题，但如果二级标题下内容超过一千五百字，或者混了多种信息类型，就得继续往下切。切完之后检查每个主题能否用Concept/Task/Reference归类，归不了类的要么拆，要么用通用Topic。

主题命名建议用动宾结构或明确的名词短语，比如“配置数据库连接”“错误码对照表”，避免“关于XX”“XX说明”这种模糊标题。文件名用英文小写加连字符，和主题ID对应，方便后续键管理和检索。

4.2 键管理规范的设计与落地

键（Key）是DITA复用体系的枢纽，键管理规范没设计好，后面全是坑。我的建议是分层设计：

• 全局键：产品名称、公司名称、版本号、通用界面元素名，放在顶层键映射文件里，所有项目共用。
• 项目级键：项目特有的术语、模块名，放在项目键映射里。
• 主题级键：只在单个主题内部使用的键，就近定义。

键名命名要有前缀区分，比如prod-name、ui-save-btn，避免冲突。键定义集中管理，改动走变更流程，别让写作者随手改键值。另外，键引用在发布前一定要做解析校验，DITA-OT有相关参数可以开启严格校验，把未解析的键引用报出来，别等到发布后才发现链接断了。

4.3 条件属性的规划与发布配置

条件处理（Profiling）用好了能大幅减少重复内容，用不好会让源文件变得难以维护。规划条件属性时，先明确维度：是按受众分（管理员/普通用户）、按平台分（云端/本地）、还是按产品版本分。维度不要太多，三四个足够，太多会导致组合爆炸。

属性值命名要统一，比如audience="admin"和audience="administrator"混用是灾难。建议维护一个属性值清单，写作者只能从清单里选。发布时通过Ditaval文件定义过滤规则，每个交付物对应一个Ditaval，明确包含哪些值、排除哪些值。

这里有个容易忽略的点：条件过滤是在发布时生效的，源文件里所有内容都在。如果过滤规则设计不当，可能出现“该显示的被过滤掉了”或者“不该出现的漏出来了”。建议每次发布前用DITA-OT的调试模式检查过滤结果，或者做抽样验证。

4.4 发布流水线的搭建与样式定制

发布流水线的基本形态是：源文件版本管理（Git等）→ 触发构建 → DITA-OT转换 → 输出分发。构建可以用CI工具自动化，每次提交后自动跑一遍转换，把错误尽早暴露。

样式定制是工作量最大的环节。PDF输出基于XSL-FO，需要改XSLT模板；HTML输出基于HTML5转换，改CSS和模板。建议先从HTML输出做起，因为调试成本低，改完刷新就能看效果。PDF样式等HTML稳定后再攻，重点解决中文字体、行距、目录、页眉页脚这几个高频问题。

定制样式时尽量用插件机制，别直接改DITA-OT核心文件。插件目录结构按官方规范组织，用plugin.xml声明扩展点。这样DITA-OT升级时，插件可以平滑迁移，核心文件保持干净。

5. 常见问题排查与避坑心得

5.1 发布报错的高频原因速查

DITA-OT报错信息有时候比较晦涩，我整理了一张速查表，覆盖大部分常见情况：

排查时养成看日志的习惯，DITA-OT的日志会标出出错的文件和行号，顺着找基本能定位。另外，把构建过程拆成小步骤单独跑（先验证Map，再转换单个主题），比一次性跑全量构建更容易定位问题。

5.2 内容复用失效的典型场景

复用失效是DITA项目里最隐蔽的问题，表面看结构都对，实际维护时发现改一处要改十处。典型场景有几个：

Conref引用了过大的粒度。有人图省事，把整个section甚至整个topic用conref引过来，结果源内容一改，引用点的上下文全乱。正确做法是引用最小必要粒度，比如一个段落、一个步骤、一个表格行。

键引用和直接写死混用。同一个产品名，有的地方用键引用，有的地方直接写文字，改产品名时漏改。这个只能靠规范约束加发布前扫描，用脚本检查源文件里是否存在硬编码的产品名。

条件过滤替代了复用。本该用conref复用的内容，用条件属性复制了两份，只是打了不同标签。这样源文件里内容翻倍，维护成本也翻倍。判断标准：如果两段内容文字完全相同只是受众不同，用conref；如果内容有实质差异，才考虑条件处理。

5.3 团队协作中的规范落地技巧

DITA项目的成败很大程度取决于规范能不能落地。我的经验是：

规范要少而硬。一开始别搞十几页的写作规范，先定三条铁律：主题颗粒度上限、键命名规则、条件属性值清单。这三条守住，基本盘就稳了。其他规范随着项目推进逐步补充。

校验要自动化。用Schema校验、用脚本扫描硬编码、用构建流水线做发布前检查，把规范检查变成机器的事，别指望人工review能兜住。

培训要场景化。别讲抽象的标准条文，直接拿团队自己的文档做案例，现场演示怎么切主题、怎么建键、怎么配过滤。写作者看到自己熟悉的内容被结构化之后确实更好维护，接受度会高很多。

5.4 什么情况下不该上DITA

这一点必须说清楚，DITA不是万能药。以下几种情况，我建议慎重或者干脆别上：

内容量很小，就几篇文档，且长期不怎么更新。这种情况下结构化的投入产出比很低，用Markdown加静态站点生成器可能更划算。

内容以营销文案、创意表达为主，结构灵活多变。DITA的严格结构会束缚表达，这类内容不适合。

团队没有技术维护能力，也没有预算购买商业工具和服务。DITA-OT的配置和样式定制需要持续投入，没人维护的话会变成烂尾工程。

产品线单一、交付物单一、复用需求弱。DITA的价值在复用和多交付物，如果这两点都不成立，上DITA的收益有限。

判断标准其实很简单：问自己三个问题——内容是否需要多格式多交付物输出？是否存在大量跨文档复用需求？是否有长期维护和多人协作的诉求？三个都是肯定，DITA值得考虑；只有一个肯定，再掂量掂量。

6. 我对DITA在国内落地的一点观察

折腾DITA这些年，我最大的体会是：标准本身是成熟的，工具链是够用的，真正的变量在人。国内团队落地DITA失败的案例，极少是因为标准理解不到位，多数是内容治理没跟上、写作习惯转不过来、或者工具链维护断档。技术问题都有解，组织问题才是硬骨头。

另一个观察是，国内对DITA的支持生态在慢慢变好，商业工具的中文化程度在提升，开源社区的中文资料也比前几年丰富。但深度定制的服务能力仍然集中在一线城市和少数服务商手里，二三线城市的团队想找本地支持不太容易。这种情况下，团队内部培养一两个懂DITA-OT和XSLT的“种子选手”就特别重要，哪怕不是全职，能解决日常的构建和样式问题，项目就能转起来。

最后分享一个实操小技巧：DITA项目启动时，先拿一个最小的产品文档做试点，完整跑通“写作-组织-发布-样式”全流程，把坑都踩一遍，再推广到全量内容。试点阶段别追求完美，能出PDF、能出HTML、键引用能解析、条件过滤能生效，这四件事跑通就算成功。剩下的优化，边用边改，比一次性设计一个完美方案要靠谱得多。