维基真的适合存储用于软件开发的文档吗？[关闭]

每个人都知道，有据可查的软件开发会带来成功。但是，这通常意味着文档中不仅会涉及纯文本，而且还会涉及二进制内容，例如UML图。我听说很多人都这么说。版本控制系统不适用于二进制文件。我完全理解并同意这个问题。我问了几个经验丰富的开发人员，最好的存储文档的位置应该在哪里，而我得到的答案是“ wiki”。Wiki很好，但是我考虑了另一个潜在的问题。存储在版本控制系统中的源代码如何连接到Wiki中的相关文档？假设有人克隆了git或mercurial的存储库。他/她如何轻松找到文件？还是我只是错过了什么？

我知道某些Wiki系统具有与源代码控制系统集成的能力。但是我关心的不是集成能力。如果您已经从git仓库中克隆了源代码，并且过了一会儿，那么您将在火车上并希望继续在火车上离线工作（这是DVCS的一大功能）。然后您突然意识到，由于您在火车上离线工作，因此您无权访问文档。另一方面，如果文档存储在git存储库中，则可以访问克隆了存储库的文档。

WIKI是否真的适合存储用于软件开发的文档？

与其编写文档，pdf和其他类型的文件，不如不释放WIKI作为协作工具的全部潜力？您可以在此处编写文档，附加图表，甚至更好：如果使用Fitnesse，则可以将Wiki页面转变为真正有用的文档，因为它们可以成为可执行的规范。

人人都知道，有据可查的软件开发会成功

注意这一点。文档将不会成功，因为它们不会将废话变成好代码。但是文档是成功软件的一部分。但仅仅是一部分，他们将不会取代良好实践和好人。

由于有多个答案指向Trac作为建议，因此我想提出一个类似但更好的选择：Redmine。

Redmine是一个项目管理解决方案，包括Wiki，文档存储库和版本控制集成。根据我的经验，它也是用Ruby on Rails编写的，并且比Trac更容易扩展和破解。

除了一切之外，它真的非常易于使用，并且很容易使团队使用它。

特征：

• 多个项目支持
• 基于角色的灵活访问控制
• 灵活的问题跟踪系统
• 甘特图和日历
• 新闻，文件和文件管理
• 提要和电子邮件通知
• 每个项目Wiki
• 每个项目论坛
• 时间跟踪
• 用于问题，时间输入，项目和用户的自定义字段
• SCM集成（SVN，CVS，Git，Mercurial，Bazaar和Darcs）
• 通过电子邮件创建问题
• 多种LDAP身份验证支持
• 用户自我注册支持
• 多语言支持
• 多数据库支持

对于您的离线需求，我不喜欢将设计文档中的版本控制弄乱的想法。我确定您有问这个问题的理由，但是实际上您有多少离线时间需要访问设计文档？这确实是一个极端的案例。

正如您提到的，某些Wiki（例如Ikiwiki）具有将其数据存储在Git中的能力。鉴于此，您可以将文档作为Git子模块链接到常规源存储库下。

通过上述设置，拉动源代码并更新子模块将拉动文档的最新副本。离线时，您可以随意编辑每一个。当您返回网络时，两者都可以推回到您正在使用的任何共享位置。

尴尬的是，无论何时更新文档（甚至通过Ikiwiki Web界面），您都还需要更新Git源存储库中的相应子模块。但是，这很容易实现自动化。

将文档与源代码存储在同一存储库中是有意义的。Sphinx对我来说似乎是一个不错的选择。

• 它以reStructuredText文件作为输入，易于编辑和比较
• 它生成超链接的输出（HTML，PDF等）
• 您可以引用您的源代码（Python，C，C ++，JavaScript）

Trac提供了Subversion的界面，集成的Wiki和便利的报告功能。 http://trac.edgewall.org/
但我不知道您安装的堆栈。

我不会尝试适应离线工作。我将使用最易于与所有人一起使用的资源。例如，如果您正在编写PHP代码，则建议使用PHPDocumentor可以生成的内联文档。它可以在任何地方生成，并且有Trac插件。然后，无论在线还是离线，您都可以相当快速地访问文档。

关键在于可用性。如果难以维护，它将开始遭受痛苦。当它开始受到影响时，文档质量就会下降。发生这种情况时，人们开始抱怨，然后一切都变得艰难。

使用Wiki存储文档对我来说很有意义。

准确性是DVCS的一个示例，它可以更紧密地集成Wiki内容和源代码。