我该在哪里以及如何记录我的Ruby on Rails应用程序？

Question

我正在使用 Ruby on Rails 3，并且希望除了在文件中使用注释外，内部文档也能够记录我的应用程序。为此，我想在应用程序的某些已有文件夹中创建文档文件。

但是我有一些问题/疑虑：

1. 我必须在 RoR 应用程序的哪个文件夹中创建文档文件？

   注意：我只想允许开发人员查看这些文件。无公开访问。

2. 你推荐使用什么文件扩展名？

   注意：文档中要插入简单文本。

3. 关于这个话题，您有任何一般性的建议吗？

   例如：这种做法是否错误？

- user502052

Answer 1

有一个名为doc的文件夹，您可以将文档放在其中（只有public是可访问的），README_FOR_APP是介绍应用程序和为私人用户添加注释的地方。 readme.rdoc或readme.md位于根目录中，是另一个提供说明和版权的好地方。如果您查看GitHub上的一些开源项目（例如devise），您将看到此文件默认显示在项目目录下。

我坚持使用doc文件夹来进行更具体的文档编写，我使用odt和ods来进行需求分析，并使用BOUML的默认扩展名来进行uml建模。使用TODO.TXT来提醒我要实现的功能（在代码中仅使用关键字TODO来表示需要修复的内容）。

有一个用于文档编写的插件（yard），我认为他们对此非常重视。

如果您不想在生产服务器上使用文档，请使用git配置将其删除，我们有两个服务器，一个用于开发，另一个用于生产。 编辑 如果您的文档需要不同用户频繁更新（特别是在开始时），您可能更喜欢将该文件夹与Ubuntu One或Dropbox同步，甚至使用类似Google Docs的东西。

- ecoologic

Answer 2

嗯，这不是一个关于Rails的问题，而是一个关于项目组织的问题。

Rails特别在根目录生成了一个doc目录，看起来是放置与应用程序相关文档的地方。然而，你需要问问自己是否要将独立的文档（而不是直接与应用程序的源代码/开发有关）放在同一代码仓库中（假设你正在使用SCM系统）。如果你撰写的文档与项目的开发实际上没有关系，而是与其使用或其他目标（如业务目标等）有关，则这种文档应该放在其他地方，特别是（取决于你计划如何部署应用程序），考虑到每次检出应用程序代码时都会不必要地下载所有这些文档（除非它是有关运行服务器相关维护脚本的文档等，在服务器上确实不需要它）。

如果你只是编写简单的文本，则使用.txt扩展名是有意义的。但实际上，只需使用你和你的团队熟悉的任何文件（及其适当的扩展名）即可。

再次强调，这取决于文档的目的和受众。如果对应用程序开发人员或部署/管理目的没有用处，则它实际上不属于应用程序，应该将其存储在单独的存储库或专门用于与需要了解此文档的人共享的系统中，可以是服务器上的简单共享文件夹或更专业的东西。

- darkliquid

Answer 3

为什么不使用doc子目录和rake doc:app呢？

- ybakos