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

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

3年前关闭。




Improve this question




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

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

通常，我们希望提供以下类型的文档(按复杂度排序)。

快速入门指南

使用指南

网页界面中的帮助文本

管理手册

培训手册

内部文档(针对开发人员)

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

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

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

所以我想知道:

是否有关于如何编写可重用文档的最佳实践？

大(ger)公司如何管理他们的文档？

有没有办法将所有文档放在一个地方，并为不同的目标群体编译不同的版本，而无需手动处理更改？

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

Answer 1

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

它们还使从相同内容生成多种输出格式变得非常容易，例如网站管理手册的 HTML 版本和产品随附的 PDF 版本。

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