文档和版本控制

Question

鉴于我即将开始的项目将产生文件。

最佳做法是什么？

文件是否应该与代码和资产一起使用，还是应该有单独的文档存储？

修改

我想要一个维基但是我需要打印文件等...这是一个大学项目。

Answer 1

这真的取决于你的团队。在我工作的地方，我们将文档保存在与我们的团队网站链接的Wiki中。出于运输文档的目的，可以导出wiki，我们通过解析器运行它，该解析器为了客户目的“模仿”文档的外观和感觉。

使用代码存储文档（通常在源存储库中）并不是一个坏主意。只要确保将它们分开。例如，保留一个 docs 文件夹，该文件夹与存储库中的 src 文件夹位于同一级别。通过这种方式，您可以快速发送当前文档，您可以轻松地跟踪修订，任何对项目有兴趣的人都可以立即跳转，而无需前往多个位置获取信息。

Answer 2

将其存储在源代码管理中很好。

Answer 3

这是一个有趣的问题 - 基本上，其他人所说的是关于生成的文档，源文件和模板/等等。应存储在源代码管理中并在构建过程中生成。

至于要求/规格/等。文档，我有两种方式，我更喜欢使用SharePoint或专为文档共享/版本控制而设计的Wiki /文档门户。原因是，大多数非开发人员不习惯使用源代码控制系统，如果使用像Word这样的二进制格式，则无法获得智能合并的任何优势。此外，基于互联网的访问非常方便，因此您可以在分布式团队中参考和处理文档，而无需安装额外的软件。

Answer 4

以下是2017年的选项摘要和我的经验：

（极端1）完全外部（例如wiki，Google Docs，LaTeX，MS Word，MS Onedrive）

• 人们并不担心让它保持最新状态（其中有一半人甚至不知道在哪里可以找到需要更新的页面，因为它已经超出了战壕）。
• wiki平台是“强制用户界面” - 您的数据存储在其专有模式中，并且不容易使用简单的文本编辑器进行检查（Confluence更糟糕，因为您根本无法访问纯文本内容）

（极端2）完全内部（例如javadoc）

• 污染了源代码，通常程度太低而无法使用。编写良好的源代码仍然是低级文档的最佳形式。
  • 但是，我认为package-info.java文件未得到充分利用。

（余额）共置文档（例如README.md）

• 一个很好的中途解决方案，具有版本控制的优点。如果单个README.md文件不够，请考虑doc/文件夹。我已经看到的唯一缺点是，是否提供控制有用的图形（例如png文件）和冒险使回购膨胀的风险。
  • 避免此问题的一个有趣方法是使用明文图工具（我发现Grapheasy和Text Diagram是一股新鲜空气）。
即使您的渲染引擎随着岁月的流逝而变化，也可以轻松读取
• 明文。

Github的成功在很大程度上要归功于位于项目根目录中的README.md。

这种方法的一个很小的缺点是，每次编辑README.md文件时，您的持续集成系统都会触发新的构建。

Answer 5

如果您正在编写与产品的每个版本相关联的版本化用户文档，那么将文档放在源代码管理中以及相关的产品版本是有意义的。

如果您正在编写内部开发人员文档，请使用自动内部源代码文档（javadoc，doxygen，.net注释等）来获取源级文档，并使用项目Wiki来获取设计级文档。

Answer 6

我认为业内大多数人都没有真正遵循最佳实践，当然这也取决于你的情况。

在一个敏捷的环境中，你会有一个非常迭代的发布过程，你会想要“轻装上阵”。在这个特殊情况下，Jason建议单独的Wiki确实很有用。

在降水/大爆炸模型中，您将有更好的机会在每个新版本中获得适当的文档更新。此外，您还需要清楚地记录已达成一致的要求的版本，并为您对要求所做的每一个微小变更提供大量文档（由于它对后续阶段的影响）。通常，如果文档可以与版本控制的源代码一起使用，那么它是最好的。

Answer 7

您使用的是任何类型的自动文档还是完全手动？假设您使用的是自动文档系统，文档或多或少会动态生成，并且会成为代码本身的一部分。

对我来说，（假设你可以使用你使用的任何代码），这将是处理它的首选方法，因为你根本不需要维护文档源。