编写可重用文档的最佳实践

Question

我们公司的产品线很小，但用量可能非常复杂。

目前的情况是（内部和外部）文档分布在各个地方：Wiki，Adobe Indesign文件，文档，文本文件，代码中的内联文档，产品Web界面中的帮助文本等。文档由一小组开发人员编写，但如果您想更新所有其他来源，几乎不可能跟踪所有更改。

一般而言，我们希望提供以下类型的文档（按提高复杂性排序）。

• 快速入门指南
• 用户指南
• webinterface中的帮助文本
• 管理手册
• 培训手册
• 内部文档（面向开发人员）

所有手册的大部分内容都是相同的（一般信息），部分内容仅在最后三种类型中，内部文档应包含所有内容。

我已经看过一些通常在stackoverflow上推荐的工具（即DITA，docBook，pandoc，doxygen，Sphinx）。除了DITA（或DITA OT）和docBook之外，这些工具似乎都没有关注可重用内容。但这两个工具似乎也非常复杂，用户不友好。

当然可以只使用LaTeX，只包含适合您要构建的文档类型的部分。但这对我来说似乎是一种解决方案。

所以我想知道：

• 是否有关于如何编写可重用文档的最佳实践？
• 大（ger）公司如何管理他们的文件？
• 有没有办法将所有文档放在一个地方，并为不同的目标组编译不同的版本，而无需手动处理更改？

对于内部文档，最好包含代码中的部分，但这不是强制性的。使用版本控制（git）来维护内容也是很好的。

Answer 1

听起来您正在寻找单一来源文档工具，例如Author-It或MadCap Flare。这些允许您编写一次主题，然后将这些主题嵌入到多个文档中（因此，当您进行更改时，您只需要在一个位置执行此操作）。

它们还可以很容易地从同一内容生成多种输出格式，例如您网站的管理手册的HTML版本以及产品附带的PDF版本。

聘请技术作者来帮助您进行设置可能是一项很好的投资。

Answer 2

DITA是为此而设计的，并提供了许多重用机制，如keyrefs，conkeyrefs，过滤器等。您可以找到介绍视频here，它解释了这些机制。您必须仔细权衡，依靠专有工具/格式来保存文档（例如，使用Author-It或MadCap或任何其他竞争工具）。这可能是没有任何返回点的单行道。如果要切换文档工具集，例如因为您的供应商提高了价格或停止支持您的工具，所以您遇到了问题。 DITA可能更贵，但它是一个开放的标准。