编写可重用文档的最佳实践 [关闭]答案

【问题标题】：Best practice for writing reusable documentation [closed]编写可重用文档的最佳实践 [关闭]
【发布时间】：2015-10-23 07:37:48
【问题描述】：

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

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

一般来说，我们希望提供以下类型的文档（按复杂度排序）。

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

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

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

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

所以我想知道：

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

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

【问题讨论】：

标签： documentation documentation-generation reusability docbook dita

【解决方案1】：

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

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

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

【讨论】：

谢谢。 “单一来源文档”是我缺少的关键字。我在 SO 上找到了另一个与此主题相关的有用线程：stackoverflow.com/questions/1283348/…
我很高兴它有帮助。请考虑通过单击对勾符号将此标记为答案。请注意，询问哪些工具可用的问题不太适合 Stack Overflow，并且可能会被关闭（因为它们往往会生成一长串主观选项而不是确定的答案）——尽管不是我投反对票你;-)

【解决方案2】：

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

【讨论】：