企业官网建设流程全解析

很多团队第一次接触结构化写作，都是从一份"看起来像XML、读起来像说明书"的规范文档开始的。DITA就是这样一个东西——名字听着陌生，但只要你所在的项目需要把同一批内容发布到多个渠道、多个产品型号、多个语言版本，它几乎绕不开。我最早接触DITA是在一个技术文档迁移项目里，当时手里有几百篇Word文档，每篇都要维护三到五个变体，改一个参数要在十几个文件里同步，改漏一处就是线上事故。后来把内容拆成主题、用DITA重组，维护成本直接砍掉一大半。这篇就围绕DITA标准本身讲清楚它是什么、核心机制怎么运转，以及在国内实际落地时会遇到哪些现实问题、有哪些可用的工具和替代路径。不管你是刚被安排调研结构化写作的技术写手，还是想给团队引入内容复用体系的技术负责人，下面这些内容都能直接拿去用。

1. DITA到底解决了内容维护里的哪个死结

1.1 从"文档思维"到"主题思维"的转变

传统写作的基本单位是"文档"——一份用户手册、一份安装指南，从头写到尾，章节顺序固定。这种模式在单一产品、单一渠道下没问题，但一旦产品线扩张，问题就来了：同一段"安全注意事项"在五本手册里各写一遍，改一处要改五处；同一个功能说明在网页版和PDF版里措辞不一致，用户投诉；翻译团队拿到的是整本手册，改了一个词也要重新走一遍完整流程。

DITA的核心主张是把写作单位从"文档"降为"主题"（Topic）。一个主题只讲一件事，比如"如何更换滤芯""错误码E102的含义"，它自带标题、正文、元数据，是一个可以独立存在、独立复用、独立翻译的最小单元。文档不再是一段连续文字，而是由若干主题按地图（Map）组装出来的产物。这个转变听起来只是粒度变细，实际影响很深：内容从"一次性消费品"变成了"可管理资产"，复用、变体、多语言发布才有了工程化的基础。

我常拿乐高打比方：传统写作是直接雕一整块木头，想改形状只能重雕；DITA是先做标准积木，再按图纸拼。积木本身不关心最后拼成城堡还是飞船，这正是复用的前提。

1.2 三类主题与两种复用机制

DITA标准里最常用的主题类型有三种，分工很明确：

这三种类型不是随便分的，它对应读者使用文档的三种真实场景：想理解、想操作、想查证。把内容按这个维度归类，写作时就不会把原理和步骤混在一段里，读者也能快速定位。

复用机制有两个层次。第一层是主题级复用：同一个Task主题可以被十张Map引用，改一次全部生效。第二层是内容级复用，靠conref（内容引用）和keyref（键引用）实现。conref适合引用一段固定内容，比如产品名称、法律声明；keyref更灵活，它引用的是一个"键"，键的实际值在Map里定义，同一套主题配不同的Map就能输出不同产品型号的文档。这个机制是DITA做变体发布的关键，后面会展开讲。

1.3 为什么是XML而不是别的格式

有人会问，用Markdown加个引用机制不行吗？小规模可以，规模一大就撑不住。DITA选择XML作为底层格式，原因有几个：XML的严格结构让内容可以被程序可靠解析和校验，DTD或Schema能约束"Task主题里必须有步骤"这类规则，机器能自动检查；XML的命名空间和属性机制天然支持元数据标注，分类、过滤、条件发布都靠它；再加上XSLT转换能力，同一份源内容可以输出PDF、HTML、帮助系统等多种格式。

代价也很明显：XML对写作者不友好，手写标签效率低、易出错。所以实际项目里几乎没人直接手写DITA源码，都是用专用编辑器或者带插件的写作工具。这一点在后面讲国内工具链时会重点说。

2. 拆开DITA的信息架构：Map、Topic与Ditaval

2.1 Map是发布的总控台

Map（.ditamap文件）是DITA的组装说明书，它定义了一本书或一个帮助系统包含哪些主题、以什么顺序排列、层级关系如何。一个Map里可以嵌套子Map，大型项目通常按产品模块拆成多个子Map，最后用一个主Map汇总。这样做的好处是不同团队可以并行维护各自的子Map，互不干扰。

Map里还能定义keyref的实际值、定义主题的复用关系、挂载Ditaval过滤条件。可以说，源内容是散落的主题，Map决定了它们最终以什么面貌呈现给读者。我见过不少团队主题写得不错，但Map组织混乱，结果发布出来的文档结构一塌糊涂——Map的设计其实比单个主题的写作更考验架构能力。

2.2 条件处理与Ditaval过滤

变体发布是DITA的招牌能力，实现靠的是条件属性加Ditaval文件。写作时给元素打上平台、受众、产品级别等属性，比如一段内容标注platform="pro"，发布时用一个Ditaval文件声明"只保留pro、排除basic"，转换引擎就会自动过滤。

<!-- 主题中的条件标注 --> <p platform="pro">专业版支持批量导入，单次上限五万条。</p> <p platform="basic">基础版单次导入上限五千条。</p>

<!-- Ditaval 过滤文件 --> <val> <prop att="platform" val="pro" action="include"/> <prop att="platform" val="basic" action="exclude"/> </val>

这套机制的价值在于：源文件只有一份，不同产品、不同受众的文档由发布时动态生成，不需要维护多套源。但要注意，条件属性不能滥用。我见过一个项目给每段话都打了三四个条件，结果源文件可读性极差，新人根本看不懂哪段属于哪个版本。经验做法是条件维度控制在两到三个（比如平台、受众、版本级别），超过这个数量就该考虑拆主题而不是堆条件。

2.3 链接与关系表

DITA的链接不是硬编码在正文里的，而是通过关系表（reltable）在Map层面定义。这样同一批主题在不同Map里可以有不同的关联关系，正文本身保持干净。比如"更换滤芯"这个Task，在用户手册里关联"滤芯型号对照表"，在维修手册里关联"拆机步骤"，两套关系各自定义，主题不用改。

这个设计初看有点绕，实际用起来很香：内容作者只管把主题写对，关系由信息架构师在Map里统一编排，职责分离得很清楚。

3. 国内落地DITA的真实处境

3.1 标准本身是开放的，工具链才是门槛

DITA由OASIS维护，标准文档公开可查，任何人都能实现自己的处理器。这一点对国内团队是利好——不存在授权费用问题。但标准开放不等于落地容易，真正的门槛在工具链。DITA的参考实现DITA Open Toolkit（DITA-OT）是开源命令行工具，功能完整但配置复杂，输出样式定制需要写XSLT，对没有专职工具工程师的团队来说上手曲线很陡。

国内能提供完整DITA支持的本土商业工具并不多，多数团队要么基于开源方案自建，要么采购国外编辑器配合自研发布流程。这就带来一个现实问题：中文排版、中文断行、中文字体嵌入这些本地化需求，开源方案默认支持得比较粗糙，往往需要额外定制。我在一个项目里为了让PDF输出的中文标点挤压正确，改了好几处XSLT模板，这类活儿没有现成文档，全靠试。

3.2 写作端的现实选择

让技术写手直接写XML不现实，所以写作端一般有三种路径：

• 专用XML编辑器：提供所见即所得或标签辅助输入，校验实时，适合正式团队，但采购成本和培训成本都不低。
• 结构化写作插件：在通用编辑器上装插件，降低入门门槛，适合中小团队试水。
• 轻量标记加转换：用接近Markdown的轻量语法写作，再转换成DITA，牺牲一部分结构严谨性换取写作效率。

三种路径没有绝对优劣，关键看团队规模和内容复杂度。十几人的文档团队、产品线多、翻译量大，值得上专用编辑器；三五人的小团队，先用轻量方案跑通流程更务实。我个人的建议是先用最小可行流程验证复用价值，别一上来就铺全套工具，否则很容易在工具配置阶段耗尽耐心。

3.3 发布环节的定制工作量

DITA-OT的发布流程是"预处理—转换—输出"三段式，预处理阶段解析Map、合并主题、处理条件和引用，转换阶段用XSLT生成目标格式。国内团队最常卡在输出样式上：默认的PDF样式是西文排版逻辑，中文字体、行距、标点规则都要改；HTML输出要对接自家帮助中心的前端框架，也得定制。

这块的工作量要有心理准备。一个中等复杂度的PDF插件定制，从零到可用通常要投入数周。好消息是社区有不少开源插件可以参考，坏消息是中文相关的定制案例相对少，很多细节得自己啃。

4. 一套可跑通的最小落地流程

4.1 环境搭建与目录约定

先跑通再说优化。最小环境只需要DITA-OT加一个能编辑XML的工具。目录结构建议一开始就定清楚，避免后期迁移：

project/ maps/ 主Map与子Map topics/ 所有主题文件 reuse/ 公共复用内容（声明、术语） ditaval/ 各变体的过滤文件 custom/ 自定义样式与转换插件

主题文件按产品模块分目录，文件名用英文小写加连字符，别用中文文件名——某些转换环节对非ASCII文件名处理不稳定，这是踩过的坑。

4.2 从一篇文档拆出第一批主题

不要一上来就重构全部内容。挑一篇结构清晰、复用潜力大的文档做试点，按"一个主题一件事"的原则拆分。拆分时问自己三个问题：这段内容读者是想理解、想操作还是想查证？这段内容会不会在其他文档里出现？这段内容是否随产品型号变化？答案决定了主题类型和是否需要条件标注。

拆完先不加任何条件、不做任何复用，单纯用Map组装出和原文档等价的产品，验证转换流程通畅。这一步跑通，再逐步引入conref和keyref。

4.3 用keyref做第一个变体

变体是DITA价值最直观的体现，建议作为第二个验证目标。做法是把产品名称、型号、参数上限这类会变的值抽成key，在主题里用keyref引用，不同产品的Map里定义不同的key值。

<!-- 主题中引用键 --> <p>本设备型号为 <keyword keyref="product-model"/>，最大负载 <keyword keyref="max-load"/>。</p>

<!-- Map 中定义键值 --> <keydef keys="product-model"> <topicmeta><keywords><keyword>A型</keyword></keywords></topicmeta> </keydef>

同一份主题配两张Map，输出两份型号不同的文档，源文件零改动。这个演示做出来，团队对结构化写作的接受度会明显提升——比讲十页PPT管用。

4.4 发布流水线的自动化

手工敲命令行发布不可持续，早晚要接自动化。基本思路是把DITA-OT调用封装成脚本，参数化输入Map和Ditaval，输出目录按版本号和时间戳组织。再进一步可以接入持续集成，源文件提交后自动构建、自动检查链接有效性、自动部署到测试环境。

这里有个容易忽略的点：构建失败的通知要足够醒目。结构化写作的源文件是XML，一个标签没闭合就可能导致整本书构建失败，如果通知不及时，写手会以为发布成功了。我在项目里吃过这个亏，后来强制要求构建结果推送到团队频道，失败必须有人认领。

5. 那些文档里不会写的坑

5.1 过度结构化比不结构化更糟

DITA鼓励细分主题，但细分过头会带来反效果。我见过一个项目把"点击保存按钮"单独做成一个Task主题，结果一张Map里塞了上百个微型主题，导航层级深得读者找不到北，维护时改一个流程要动十几个文件。主题的合理粒度应该是"一个读者能独立理解并完成的最小任务单元"，而不是"一个操作动作"。判断标准很简单：如果两个主题永远一起出现、分开没有任何意义，那就该合并。

5.2 条件属性是技术债的高发区

前面提过条件维度要控制，这里补充一个更隐蔽的问题：条件属性一旦加上，后续很难清理。因为没人敢确定某个条件分支是不是还有产品在用。所以引入条件属性前要有明确的命名规范和生命周期管理，废弃的产品线要及时清理对应的Ditaval配置和源文件标注，否则几年后源文件会变成没人敢碰的迷宫。

5.3 翻译流程要提前设计

结构化写作和翻译是强绑定的。DITA的翻译流程通常基于XLIFF交换格式，主题级翻译记忆的复用率比整本文档高得多，这是实打实的成本节约。但如果源文件里混入了不该翻译的内容（比如代码、产品代号），或者条件标注不规范，翻译质量会受影响。建议在写作规范里明确"哪些元素不翻译""条件标注必须用受控词表"，并且在上游做源文件质量检查，别把问题留给翻译环节。

5.4 团队能力建设比工具采购更重要

最后说个软性的。DITA落地失败的项目，多数不是工具不行，而是团队没准备好。结构化写作要求写手具备信息架构思维，这和传统写作习惯差别很大。我的经验是：先培养一到两个"种子选手"吃透标准和工具链，再由他们带动其他人；同时把写作规范做成可执行的检查清单，而不是厚厚一本没人看的文档。工具可以买，思维转变买不来。

6. 选型对照：什么情况下该上DITA，什么情况下不该

6.1 适合引入的典型信号

不是所有文档项目都值得上DITA。出现下面这些信号时，结构化写作的投入产出比才划得来：

• 同一批内容要发布到三个以上渠道或产品变体；
• 多语言翻译量大，且内容重复率高；
• 文档团队超过五人，需要并行协作和统一规范；
• 有长期维护需求，内容生命周期以年计。

反过来，如果产品单一、文档量小、更新频率低，用轻量标记语言加模板完全够用，硬上DITA只会增加负担。工具是为问题服务的，别为了用而用。

6.2 替代方案的取舍

国内团队常见的替代路径有三类：轻量标记语言加静态站点生成、基于数据库的内容管理系统、以及自研的结构化方案。轻量方案上手快、生态好，适合中小团队；内容管理系统适合需要在线协作和权限管理的场景，但结构严谨性通常不如DITA；自研方案灵活但维护成本高，除非有特殊需求否则不建议。

选型的核心不是比哪个方案更先进，而是比哪个方案和团队的实际能力、内容的实际复杂度匹配。我见过用轻量方案把多产品文档管得井井有条的团队，也见过上了全套DITA工具却因为没人维护而荒废的项目。工具是放大器，放大的是团队本来的能力。

6.3 渐进式迁移的节奏建议

如果决定上DITA，别搞大爆炸式迁移。合理的节奏是：第一阶段选一篇文档做试点，验证工具链和复用价值；第二阶段扩展到一条产品线，建立写作规范和检查清单；第三阶段再推广到全团队，同时把发布流程自动化。每个阶段设明确的验收标准，比如"试点阶段结束时，同一内容在两个变体下的维护工时下降三成"。用数据说话，比用理念说服人有效得多。

7. 我对这套体系的实际体会

折腾过几个结构化写作项目之后，我最大的感受是：DITA的价值不在标准本身，而在它逼着团队把内容当成工程资产来管理。主题拆分、条件标注、键引用这些机制，本质上都是在回答"这段内容属于谁、会被谁用、什么时候失效"。把这些问题想清楚了，哪怕最后没用DITA，用别的方案也能做出高质量的内容体系；想不清楚，上了再标准的工具也是一团乱麻。

如果让我给准备入门的团队一句实在话：先别急着研究标准文档的每一章，找一篇你手上复用最多的文档，用最小工具链拆一遍、发一遍、改一遍，把整个闭环走通。走通之后你自然知道下一步该补什么。标准是地图，路得自己走。