关闭。这个问题是opinion-based .它目前不接受答案。
想改善这个问题吗?更新问题,以便可以通过 editing this post 用事实和引文回答问题.
3年前关闭。
Improve this question
我们公司的产品线比较小,但是使用起来可能很复杂。
目前的情况是(内部和外部)文档分布在各个地方:Wiki、Adobe Indesign 文件、文档、文本文件、代码中的内联文档、我们产品的网络界面中的帮助文本等。文档由一小群开发人员,但如果您想更新所有其他来源,几乎不可能跟踪所有更改。
通常,我们希望提供以下类型的文档(按复杂度排序)。
所有手册(一般信息)的大部分内容都是相同的,有些内容只是最后三种类型,内部文档应该包含所有内容。
我看过一些在 stackoverflow 上经常被推荐的工具(即 DITA、docBook、pandoc、doxygen、Sphinx)。除了 DITA(或 DITA OT)和 docBook,这些工具似乎都没有关注可重用的内容。但这两个工具似乎也非常复杂且用户不友好。
当然,可以只使用 LaTeX 并只包含适合您要构建的文档类型的部分。但这对我来说似乎是一种解决方法。
所以我想知道:
对于内部文档,最好包含代码中的部分内容,但这不是强制性的。使用版本控制 (git) 来维护内容也很好。
最佳答案
听起来您正在寻找单一来源的文档工具,例如 Author-It或 MadCap Flare .这些使您可以编写主题一次,然后将这些主题嵌入到多个文档中(因此当您进行更改时,您只需在一处进行更改)。
它们还使从相同内容生成多种输出格式变得非常容易,例如网站管理手册的 HTML 版本和产品随附的 PDF 版本。
聘请技术作者来帮助您进行设置可能是一项不错的投资。
关于documentation - 编写可重用文档的最佳实践,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/31749306/