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

Question

我正在使用Ruby on Rails 3，除了在文件中使用注释之外，我还想开始记录内部我的应用程序。为了做到这一点，我想在我的应用程序中已经可用的一些文件夹中创建文档文件。

但我有一些疑问/怀疑：

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

   注意：我想允许仅限开发人员查看这些文件。没有pubblic访问。

2. 您建议使用哪种文件扩展名？

   注意：在文档中我必须插入简单的文本。

3. 您对此主题有任何一般性建议吗？

   示例：这是一种错误的方法吗？

Answer 1

有一个名为doc的文件夹，您可以放置​​文档（只有public可访问），README_FOR_APP是介绍您的应用程序并为私人用户添加注释的地方

readme.rdoc中的readme.md或root folder是指示和版权的另一个好地方，如果你看一下github上的一些开源项目（devise）你'将看到该文件默认显示在项目目录下。

我坚持使用doc文件夹获取更具体的文档，我使用odt和ods作为要求，并使用BOUML的默认扩展名为uml。 TODO.TXT提醒我要实现的功能（以及代码中的关键字TODO以便修复）

有一个文档插件（yard），我认为他们好好照顾他们的。

如果你不想（而你没有）生产服务器上的文档使用你的git配置删除它，我们有两个服务器，一个用于开发本地，一个用于生产的外部服务器。

编辑如果您的文档经常受到不同用户的更新（特别是在开头），您可能更喜欢将该文件夹与ubuntu one或dropbox同步，甚至可以使用google docs之类的内容

Answer 2

嗯，这不是一个轨道问题，而是一般的项目组织问题。

Rails特别在rails根目录中生成一个doc目录，它似乎是放置与应用程序相关的文档的地方。但是，您需要问自己是否要放置文档，如果它是独立的（而不是与所述应用程序的源/开发直接相关）在同一个存储库中（假设您使用的是scm系统）。如果您正在编写的文档与项目的开发并不相关，而是与其使用或其他目的（如业务目标等）有关，那么这类事物确实属于其他地方，尤其是（取决于您计划部署的方式）您的应用程序）考虑到每次检查您的应用程序代码都会不必要地删除所有这些文档（您当然不需要在服务器上，除非它是关于运行服务器相关维护脚本的文档等）。

如果您只是撰写简单的文字，那么.txt对您的扩展程序有意义。但实际上，只需使用您和您的团队所熟悉的任何文件（及其适当的扩展名）。

同样，它实际上取决于本文档的目的以及它的用途。如果它对应用程序开发人员或部署/管理目的没有用，它根本不属于应用程序，应该存储在单独的存储库或专用系统中，以便与需要的人共享此文档它，是某个服务器上的一个简单的共享文件夹或更专业的东西。

Answer 3

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