存储软件文档的最佳方法是什么？

一个明显的答案是"内部Wiki"。 Wiki用于软件文档的优缺点是什么？ 还有其他建议吗？ 您正在使用什么作为软件文档？

Loren Segal-不幸的是，我们不支持任何文档工具来从源代码注释中编译信息，但我同意这将是存储技术文档的最佳方法。 我的问题是关于各种文档，从sysadmin类型到用户文档。

---

这是一个非常开放的问题，取决于许多因素。

一般来说，如果您使用的语言具有良好的文档生成工具(javadoc，doxygen，MS的C＃东西)，则应在方法上方编写文档，并让您的工具生成页面。这样做的好处是，您可以将文本的源代码与代码保持在一起，这意味着在逻辑上正确的位置对文本进行了组织，并且在更改方法的行为时可以轻松地对其进行编辑。

如果您没有良好的文档工具支持或无法访问源代码，那么Wiki并不是一个坏主意，但是它们是上述的第二选择。

注意：我在这里只谈论代码文档。其他工件显然不能与代码一起存储-Wiki是放置这些文档的好地方。或者，如果您使用某些CMS，则只需将其提交为docs/文件夹中的文本/ pdf /任何文件，即可通过存储库进行编辑。这样做的好处是，如果移动了存储库，它们将保留在存储库中，而Wiki则不会(必须)移动。

---

工具很重要，但是在寻找魔术工具时不要陷入困境。我找不到的工具还没有"使用微小的隐形精灵神奇地记录所有内容"复选框。 :-)

维基可以正常工作。或Sharepoint。或Google文档。或者，您可以使用SVN存储库。地狱，如果您真的需要的话，可以用笔，便条纸和文件柜来做。 (我真的不建议这样做！)

最重要的关键是您需要整个组织的支持。在许多商店中，发生的事情是他们花了很多时间和金钱在诸如Sharepoint之类的精美解决方案上，然后每个人都虔诚地使用了大约两个星期，然后人们忙于达到最新的里程碑，这是最后一个任何人都听说过。

根据您的组织，领域，开发的产品类型等，有一些解决方案，但是您需要使用一种或另一种方法来建立系统并使用它。任命某人为官方文件沙皇，给他们一个线索，并让他们每当他们说"哦，是的，下周我将完成记录……"时就将他们击中头部。如果那是需要的。 :-)

至于工具...我建议使用Atlassian的Confluence。这是一个很好的Wiki，旨在在企业环境中工作，它具有许多漂亮的功能，可以自定义，并且与Atlassian的其他漂亮的工具很好地集成在一起，并且基本上是一个非常可靠的产品。

---

软件文档？是一个非常笼统的术语。有"最终用户文档"，"开发人员文档"，"质量检查文档"。第一个通常由合格的技术作家开发。其他的可能是由Wiki，源代码的文档注释等动态形成的。所有这些东西的维护过程通常非常复杂，每个软件公司都遵循自己的方式。但是，所有这些方式都有一个必要的要点：每个代码提交者，架构师，经理，质量保证工程师都必须妥善存储每条信息，这可能会对其他信息有所帮助。并且其他人必须密切注意此物品的存放，并在需要时重新排列物品。所有这些步骤极大地改善了与开发过程相关的所有活动。

---

我开始尝试一种实现这些目标的用户文档的方法：

基于Markdown / Html / Javascript /文件的相对链接的文档，具有移植性(可以在本地文件系统上运行，或者可以将其放在网络服务器上)，屏幕截图的内置处理(交互式调整大小)以及开源，以防其他人想用疯狂的事情做些事。

您的文档源是用Markdown编写的，并在浏览器运行时通过Javascript呈现给HTML。

Mandown - http://wittman.org/mandown/

---

当前，我们使用由外部应用程序(PHP + PhpDocumenter)和各种内部Wiki解析的内联文档。有时充其量是痛苦的(主要是因为只有一个人更新wiki或文档...)

但是，我一直在考虑使用ikiwiki做内部文档。它与您的源代码计数系统(包括Git，Subversion，Mercurial，Bazaar，TLA和Monotone)集成在一起，因此所有文档都将与您的项目一起跟踪。它是用Perl构建的，并具有广泛的插件系统(包括多种标记语言，默认为Markdown)。另外，源代码管理系统是基于插件的，因此，如果不立即支持您使用的内容，则可以添加您自己的内容。如果需要，请使用您喜欢的语言，因为它也支持非perl插件。

---

假设您是在谈论代码文档还是用户文档，如果您不需要在组织外部将代码的文档分发给承包商或合作伙伴，则内部Wiki非常有用。

如果您想要可分发的代码文档，则Javadoc或DOxygen更适合。

如果您要参考用户文档，则可能需要看一下DITA。

---

是的，我们使用维基，也使用Google文档。我发现Google文档比我尝试过的大多数Wiki都要好，而且，如果您不需要跟踪所有更改，那么您将一无所获。 Google文档提供了一个良好的协作框架。

---

我的公司使用各种Sharepoint和Wiki。特定要求(如需求，演示，合同等)的共享点，而Wiki则用作帮助指导开发人员资源库的内部使用库的教程。

---