编写可重用文档的最佳实践
Best practice for writing reusable documentation
我们公司的产品线比较少，但是使用起来很复杂。
目前的情况是（内部和外部）文档散布在各个地方：Wiki、Adobe Indesign 文件、文档、文本文件、代码中的内联文档、我们产品的网络界面中的帮助文本等。该文档由一小群开发人员编写，但如果您想更新所有其他来源，几乎不可能跟踪所有更改。
一般来说，我们希望提供以下类型的文档（按复杂程度排序）。
- 快速入门指南
- 用户指南
- 网络界面中的帮助文本
- 管理手册
- 培训手册
- 内部文档（针对开发人员）
所有手册的大部分内容相同（一般信息），部分内容仅在最后三种类型中，内部文档应包含所有内容。
我看过一些在 Whosebug 上经常推荐的工具（即 DITA、docBook、pandoc、doxygen、Sphinx）。除了 DITA（或 DITA OT）和 docBook，none 的工具似乎专注于可重用的内容。但是这两个工具似乎也很复杂，而且用户不友好。
当然可以只使用 LaTeX 并只包含适合您要构建的文档类型的部分。但这对我来说似乎是一种解决方法。
所以我想知道：
- 是否有关于如何编写可重用文档的最佳实践？
- 大（德国）公司如何管理他们的文档？
- 有没有办法将所有文档放在一个地方，并为不同的目标群体编译不同的版本，而无需手动处理更改？
对于内部文档，最好包含代码中的部分内容，但这不是强制性的。使用版本控制 (git) 来维护内容也很好。
听起来您正在寻找 单一来源 文档工具，例如 Author-It or MadCap Flare。这些使您可以编写一次主题，然后将这些主题嵌入到多个文档中（因此当您进行更改时，您只需在一个地方进行）。
它们还使从相同内容生成多种输出格式变得非常容易，例如HTML 版本的网站管理手册和产品随附的 PDF 版本。
聘请技术作者来帮助您进行设置可能是一项不错的投资。
DITA 就是为此而生的，它提供了许多重用机制，例如 keyrefs、conkeyrefs、过滤器等。您可以找到一个介绍视频 here，它解释了这些机制。您必须仔细权衡，依赖专有的 tool/format 文档是否是个好主意（例如，使用 Author-It 或 MadCap 或任何其他竞争工具）。这可能是一条没有任何 return 点的单行道。如果你想切换你的文档工具集，例如因为您的供应商提高价格或停止支持您的工具，所以您遇到了问题。 DITA 可能更贵，但它是一个开放标准。
我们公司的产品线比较少，但是使用起来很复杂。
目前的情况是（内部和外部）文档散布在各个地方：Wiki、Adobe Indesign 文件、文档、文本文件、代码中的内联文档、我们产品的网络界面中的帮助文本等。该文档由一小群开发人员编写，但如果您想更新所有其他来源，几乎不可能跟踪所有更改。
一般来说，我们希望提供以下类型的文档（按复杂程度排序）。
- 快速入门指南
- 用户指南
- 网络界面中的帮助文本
- 管理手册
- 培训手册
- 内部文档（针对开发人员）
所有手册的大部分内容相同（一般信息），部分内容仅在最后三种类型中，内部文档应包含所有内容。
我看过一些在 Whosebug 上经常推荐的工具（即 DITA、docBook、pandoc、doxygen、Sphinx）。除了 DITA（或 DITA OT）和 docBook，none 的工具似乎专注于可重用的内容。但是这两个工具似乎也很复杂，而且用户不友好。
当然可以只使用 LaTeX 并只包含适合您要构建的文档类型的部分。但这对我来说似乎是一种解决方法。
所以我想知道：
- 是否有关于如何编写可重用文档的最佳实践？
- 大（德国）公司如何管理他们的文档？
- 有没有办法将所有文档放在一个地方，并为不同的目标群体编译不同的版本，而无需手动处理更改？
对于内部文档，最好包含代码中的部分内容，但这不是强制性的。使用版本控制 (git) 来维护内容也很好。
听起来您正在寻找 单一来源 文档工具，例如 Author-It or MadCap Flare。这些使您可以编写一次主题，然后将这些主题嵌入到多个文档中（因此当您进行更改时，您只需在一个地方进行）。
它们还使从相同内容生成多种输出格式变得非常容易，例如HTML 版本的网站管理手册和产品随附的 PDF 版本。
聘请技术作者来帮助您进行设置可能是一项不错的投资。
DITA 就是为此而生的，它提供了许多重用机制，例如 keyrefs、conkeyrefs、过滤器等。您可以找到一个介绍视频 here，它解释了这些机制。您必须仔细权衡，依赖专有的 tool/format 文档是否是个好主意（例如，使用 Author-It 或 MadCap 或任何其他竞争工具）。这可能是一条没有任何 return 点的单行道。如果你想切换你的文档工具集，例如因为您的供应商提高价格或停止支持您的工具，所以您遇到了问题。 DITA 可能更贵，但它是一个开放标准。