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

Question

一个明显的答案是“一个内部维基”。用于软件文档的wiki有哪些优缺点？还有其他建议吗？你用什么软件文档？

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

Answer 1

这是一个非常开放的问题，取决于很多因素。一般来说，如果您使用的语言具有良好的文档生成工具（javadoc，doxygen，MS的C＃内容），那么您应该将文档写在您的方法之上并让您的工具生成页面。优点是您可以将文本保留在您的代码旁边，这意味着它可以在逻辑上正确的位置进行组织，并且在对方法的行为进行更改时可以轻松进行编辑。

如果您没有良好的文档工具支持或无法访问源代码，维基百科是不是一个坏主意，但他们是上述的第二选择。

注：我在这里只谈论代码文档。其他工件显然不能与代码一起存储 - 维基是放置这些文档的好地方。或者，如果您使用某个CMS，则可以简单地将它们作为文本/ pdf /任何可通过存储库进行编辑的文件提交到某个docs/文件夹中。它的优点是，如果移动存储库，它们会保留在存储库中，而维基不会（必然）存在。

Answer 2

我的公司使用各种Sharepoint和一个wiki。 Sharepoint用于像需求，演示文稿，合同等特定文档，而wiki则用作开发人员存储库的帮助指南，以便使用内部开发的库教程。

Answer 3

假设您正在讨论代码文档与用户文档，如果您不需要将代码文档分发给组织外的代码的文档，承包商或合作伙伴，则内部wiki非常棒。

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

如果您指的是用户文档，您可能需要查看DITA。

Answer 4

是的，我们使用wiki，我们也使用Google文档。我发现Google文档比我尝试过的大多数wiki都要好，如果你不需要跟踪所有的变化，你什么都不会损失。 Google文档提供了一个良好的协作框架。

Answer 5

我们目前使用由外部应用程序（PHP + PhpDocumenter）和各种内部维基解析的内联文档。有时它是最好的痛苦（主要是因为只有一个人更新维基或文档...）

但是，我一直在寻找使用ikiwiki做内部文档。它与您的源代理系统（包括Git，Subversion，Mercurial，Bazaar，TLA和Monotone）集成，以便您的文档跟踪您的项目。它是用Perl编写的，有一个扩展的插件系统（包括多种标记语言，默认是Markdown）。另外，源代码管理系统是基于插件的，所以如果你使用的不是立即支持，你可以添加你自己的。用你的首选语言，如果需要的话，因为它也支持非perl插件。

Answer 6

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

降价/ HTML/JavaScript的/基于文件的相对链接的文档可移植性（可以在本地文件系统中运行，或者你可以扔掉它在Web服务器），截屏的内置处理（交互调整），和开源的情况下，其他人可能希望做的疯狂的事情的东西。

您的文档来源是写在降价，并在浏览器运行时通过JavaScript渲染到HTML。

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

Answer 7

«软件文档»是一个通用词。有“最终用户文档”，“开发人员文档”，“质量保证文档”。第一个通常由合格的技术人员开发。其他的可能是由维基动态形成的，来自源代码的文档评论等。所有这些东西的维护过程通常非常复杂，每个软件公司都遵循自己的方式。但是，所有这些方面都有一个必要的要点：每个代码提交者，架构师，经理，qa工程师必须存储安排好的每条信息，这些信息可能对其他人有帮助。如果需要的话，其他人必须密切关注这些碎片存储和重新排列碎片。所有步骤大大提高改善所有与开发过程相关的活动。

Answer 8

工具很重要，但不要太陷于寻找魔法工具。我找到的工具没有任何工具具有“使用微型隐形精灵神奇地记录一切”的复选框。 :-)

维基将正常工作。或Sharepoint。或Google文档。或者你可以使用SVN仓库。如果你真的需要，你可以用笔，信纸和文件柜来做到这一点。 （我真的不建议！）

大重要的关键是你需要有买入整个组织。许多商店会发生什么事情，他们会花费大量时间和金钱来处理像Sharepoint这样的一些奇特的解决方案，然后每个人都虔诚地使用它两周左右，然后人们忙于打最新的里程碑，这是最后一个里程碑任何人都会听到它。

根据您的组织，领域，开发产品的类型等，有几个解决方案，但这种或那种方式，你需要建立一个系统和使用它。任命一个人的官方文档沙皇，给他们一个线索，并告诉他们打人头脑，每当他们说：“哦，是的，我会完成记录下周......”。如果这是需要的。 :-)

至于工具......我想通过Atlassian的建议Confluence。这是一个很好的wiki，它的设计目的是在企业环境中工作，它有很多漂亮的功能，可定制的功能，它与Atlassian的其他漂亮工具很好地集成在一起，基本上是一个非常稳定的产品。