应该在哪里存储功能规格以及如何跟踪其修订历史记录？

Question

背景

我来自硬件开发工程背景。我们的详细规范包含修订历史，作为典型MS Word文档末尾或开头的表格。这些规范保存在与用于存储硬件设计可交付物的管理系统分开的文档管理系统中，例如原理图和电路板布局文件。有时文档管理系统不用于规范，而文件名包含文档修订号。考虑到有人会开始修改具有下层修订版的文档，这总是感觉是次优解决方案。

问题

我开始研究使用DVCS（Git）的软件项目，并计划使用Markdown而不是MS Word文档将规格/文档编写为文本文件。我喜欢在DVCS中拥有所有内容的想法，包括规范和用户文档。但是，似乎规范和文档不应存储在与实际代码相同的存储库中。这引出了我的问题：

1. 规范/文档是否应存储在与代码不同的存储库中？
2. 每个spec / doc都应该有一个单独的存储库吗？
3. 软件工程师/程序员是否通常会在其规格和文件中提供修订历史记录，因为DVCS能够提供修订历史记录？

Answer 1

1. 请勿以一些不广泛使用的模糊格式存储规范。该工具不应该规定文件的形式。这些文件可能需要由您的团队以外的人使用，他们只熟悉单词。

2. 是的，规范/文档应存储在与代码不同的存储库中。管理代码存储库与文档存储库的要求不同。您可以在文档存储库中使用相同的并行组织结构（即相同的项目名称，层次结构等），这样可以轻松找到相关文档。

3. 每个spec / doc都不应该有单独的存储库。组织应该反映代码库的组织。您是否为每个项目中的每个代码文件都有一个单独的存储库？

4. 是的，无论存储库是什么，都会在规范/文档中放置修订历史记录。文档可能需要跨组织使用，组织外的人员可能无法访问源代码管理，但可能仍需要进行更改（组织中的某个人可以管理/签入）。

更常见的情况是，文档通常需要在不同的公司部门之间使用（即由UI团队，销售人员，无法访问/熟悉存储库的营销人员进行审核）。

Answer 2

在企业界，1.和2.取决于您的存储库处理创建/访问/批准文档和代码所需的安全模型的能力。对于3.适用时，您应始终在文档中包含修订背后的深入推理。