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

我们公司的产品线很小，但使用起来很复杂

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

通常，我们希望提供以下类型的文档（按复杂性排序）

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

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

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

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

所以我想知道：

• 是否有关于如何编写可重用文档的最佳实践
• 大型（ger）公司如何管理其文档
• 是否有一种方法可以将所有文档放在一个地方，并为不同的目标群体编译不同的版本，而不必手动处理更改

---

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

听起来像是在寻找单一的源文档工具，例如或。这样，您可以编写一次主题，然后将这些主题嵌入到多个文档中（因此，当您进行更改时，只需在一个位置进行更改）

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

---

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

DITA就是为此而设计的，它提供了许多重用机制，如keyrefs、conkeyrefs、filters等。您可以找到一个介绍视频，其中解释了这些机制。您必须仔细权衡，依赖专有工具/格式编制文档是否是一个好主意（例如，使用Author it或MadCap或任何其他竞争工具）。这可能是一条没有任何返回点的单行道。如果您想切换您的文档工具集，例如，因为您的供应商提高了价格或停止支持您的工具，您就有问题了。DITA可能更贵，但它是一个开放标准。

谢谢。“单一来源文档”是我缺少的关键词。我发现了另一个与这个主题相关的有用线索：我很高兴它有帮助。请考虑通过点击滴答符号将此标记为答案。请注意，询问可用工具的问题不太适合堆栈溢出，并且很可能会被关闭（因为它们倾向于生成一长串主观选项，而不是确定的答案）——尽管不是我对您投了反对票；-）