技术文档可以实现系统集成吗？| 技术传播

在知乎上看到这样一个问题：

有没有一种支持文档的可视化工具，可以将文档保存类似于markdown那种，可以管理很多文档，又可以进行表格的可视化话展示（连接数据库）

可能大部分研发人员都有所不知，技术写作之所以被称为“技术”写作，主要有3个方面的原因。除了1）技术写作通常是用来传播技术信息，以及2）技术写作是一种区别于普通写作的写作手法，另外一个非常重要的原因是，3）技术发展被越来越多地运用于技术写作和信息传播中。

那么今天就来简单介绍一下，技术文档是如何做到与研发系统相辅相成，互相促进成全的。大家好，我是睿齐，一个技术传播者，IT行业的技术文档工程师。

如果你对文档的认识，还停留在Word编辑，那么你在技术写作领域，可能已经落后了半个世纪。说到技术文档开发的最佳实践，就不能不提到DITA。

什么是DITA？

DITA，即Darwin Information Typing Architecture（达尔文信息类型化体系结构），最初由IBM 公司发明，并得到结构信息标准化促进组织（OASIS，Organization for the Advancement of Structured Information Standards）的大力推广，是目前最广泛应用的技术文档架构方式。

DITA架构文档与普通文档的区别

阅读顺序

如果你是一个IT行业从业者，想必日常通过阅读文档获取各类信息，特别是接口信息，其实这类文档通常是采用DITA架构的文档，不知道你是否已经体会到它与普通文档在阅读时的差别？

普通文档的内容通常前后信息关联大，需要读者顺序阅读；DITA架构的技术文档则是按照技术信息类型，分为说明类（Concept）/操作类（Task）/参考类（Reference），读者可以带着目的定向阅读——了解原理/使用方法/详细信息等——通过目录（map）索引到所需信息；在需要扩展阅读时，通过链接（link）跳转到相关内容。所以，DITA架构的技术文档，可以帮助读者更快地查找信息，解决问题。

内容管理

DITA架构的技术文档，在内容的开发、管理、发布和使用，都与普通文档有很大不同，甚至可以当作资源文件，与各种接口实现对接。

普通文档的开发方式就不多介绍了。大家都或多或少地使用Word编写过文档，应该可以有切身感受。

DITA架构的技术文档，其最小编辑单位是内容模块（topic），技术文档由内容模块通过索引文件（map）构建而成。相同内容模块可以被不同文档使用，实现内容同源，这样做不仅可以大大提高文档的开发效率，降低内容的维护成本，同时也保证了内容的一致性。

发布方式

对于使用Word编写的普通文档而言，发布方式比较单一，可以发布为PDF方式，或进一步印刷成为纸质版；文档内容则很难被解耦复用。

DITA 架构的技术文档基于XML的体系结构，采用标记对的方式形成带有结构样式的内容。所以理论上，可以使用XML的场景，都可以使用DITA的内容模块。这也决定了，DITA架构的文档有丰富的发布方式，包括但不限于：

• 传统方式：发布成Word/PDF格式文档，或进一步印刷成纸质版。

• Web方式：发布成html格式文档，以在网站以网页形式展示。

• 应用软件：可集成到应用软件。例如，应用界面上的弹出式说明。

• 智能检索：可对接AI接口，返回信息。例如，智能客服等。

• 其他：你可以发挥想象力，将内容集成/发布到任何你期望的渠道上。

当然，所有这一切，都是内容同源的。也就是说，你只需要维护一套内容，就可以按照实际需求，实现多种渠道和形式的内容发布。

Docs As Code

Doc As Code是当下比较流行的一个技术文档开发理念，一方面可以将文档像代码一样，并列进行管理；一方面可以将文档内容，与系统更好地集成。

Doc As Code是一个比较垂直的专门领域，相关方面很多，在此不展开介绍。

DITA架构技术文档的开发工具

DITA是一种内容的架构方式，理论上说，只要按照DITA架构思想构建内容，即时是使用传统的Word进行文档开发，也可以构建出DITA架构的技术文档；但实际上，问题的关键是，使用Word开发的文档，难以实现细粒度的内容管理，以及同源多渠道发布，所以需要专业工具来支持。

可以支持DITA架构的文档工具非常丰富。有的功能强大，但是贼老贵；有的免费开源，但是只提供基本功能，高级功能需要自行实现，而且通常对中文字支持也不是很友好。另外，针对不同的文档场景，也会有专门的工具，例如Doxygan比较适用于接口说明（Reference）这类文档的开发和管理。

在此仅就我所知范围，简单地列举一两个。

分类	软件名称	说明
商用软件	- Arbortext Editor - Xmental	功能丰富；价格昂贵；适用于大型企业大规模文档开发
中端软件	- Oxygen XML编译器	基本功能健全；价格适用；适用于对DITA文档有需求，但是规模不大的文档开发
免费开源	- 各种MarkDown编译器 - Doxygen	功能简单；免费开源；对中文支持部友好；发布问题多，需要自行解决。

MarkDown+Github是目前开源技术领域比较流行的文档开发方式，非常轻量且易于管理、集成，同时还是免费的。

结论

由于科技研发的工作越来越细分，包含技术写作在内的技术传播，也逐步形成一个专门领域。将技术与内容相结合，为技术信息发布提供了更多可能性。

其他推荐：

实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播

技术传播是一片蓝海 | 技术传播

访谈：TC无处不在，只是我们没有发觉 | 技术传播

这次他们说好要“讲真的” | 传播

在座都别吵了，你们还有我

一本培养强迫症患者的说明书 | 技术传播

就像用心做好日本料理 | 技术传播

顽固的老头子与无聊的说明书 | 技术传播

转战新媒体 | 技术传播

评测：王者荣耀的用户帮助系统 | 技术传播

让爸爸妈妈也能享受到科技发展带来的便利 | 技术传播

企业级信息管理系统初创方案构思 | 技术传播

 

睿齐

技术传播从业者

品牌内容策划

自由摄影师

自由撰稿人

汪力迪

公众号：techcomm / htstory

微信号：bgrichi

邮箱：hash_0813@163.com