I am using Ruby on Rails 3 and I would like to start to document internally my application in addition to use comments in files. In order to do that I thought to create documentation files in some folders already available in my application.
我正在使用Ruby on Rails 3，除了在文件中使用注释外，我还希望开始在内部记录我的应用程序。为了做到这一点，我想在我的应用程序中已经有一些文件夹中创建文档文件。
But I have some questions/doubts:
但我有一些疑问:
-
Where (in which folder of the RoR application) I must create documentation files?
在哪里(在RoR应用程序的哪个文件夹中)必须创建文档文件?
Notice: I would like to allow only developers to view these files. No pubblic access.
注意:我希望只允许开发人员查看这些文件。没有pubblic访问。
-
What file extension do you recommend to use?
您建议使用什么文件扩展名?
Notice: in documentation I have to insert simple text.
注意:在文档中，我必须插入简单的文本。
-
Have you any general recommendation to do about this topic?
关于这个话题，你有什么一般性的建议吗?
Example: is it a wrong approach?
这是一种错误的做法吗?
3 个解决方案
#1
2
There is a folder called doc where you can put your documentation (only public is accessible anyway), README_FOR_APP is the place where to introduce your application and put notes for private users.
有一个叫做doc的文件夹，你可以把你的文档放在那里(只有公众可以访问)，README_FOR_APP是介绍你的应用程序的地方，并为私人用户提供笔记。
readme.rdoc or readme.md in the root folder is another great place for instructions and copyrights, if you have a look at some opensource project on github (devise) you'll see that this file is displayed by default under the project directory.
自述文件。rdoc或readme。根文件夹中的md是指令和版权的另一个好地方，如果您查看github上的某个opensource项目，您将看到该文件在项目目录下默认显示。
I stick with the doc folder for more specific documentation, I use a odt and ods for requirements and the default extension of BOUML for uml. TODO.TXT to remind me features to be implemented (and just the keyword TODO in the code for things to fix)
对于更具体的文档，我坚持使用doc文件夹，对需求使用odt和ods，对uml使用BOUML的默认扩展。待办事项。TXT来提醒我要实现的特性(以及需要修改的代码中的关键字TODO)
There is a plugin for documentation (yard) and I think they took good care of theirs.
有一个文档插件(yard)，我认为他们很好地照顾了他们。
If you don't want (and you don't) the doc on the production server remove it with your git configuration, we have two server, one local for development an external one for production.
如果您不想(而您不希望)生产服务器上的doc删除它与您的git配置，我们有两个服务器，一个本地的开发一个外部的生产。
EDIT If your documentation is subjected to frequent update from different users (especially at the beginning), you may prefer to have that folder synchronized with say ubuntu one or dropbox or even use something like google docs.
如果你的文档经常从不同的用户那里得到更新(特别是在开始的时候)，你可能更喜欢与ubuntu one或dropbox同步，或者甚至使用谷歌文档。
#2
1
Well, this isn't so much a rails question as a general project organisation question.
这与其说是一个rails问题，不如说是一个通用的项目组织问题。
Rails in particular generates a doc directory in the rails root directory which seems like the place to put documentation related to the application. However, you need to ask yourself whether or not you want to be placing the documentation, if it's standalone (rather than being directly related to the source/development of said application) in the same repository (assuming you are using an scm system). If the documentation you are writing isn't really related to the development of the project, but rather it's usage or some other purpose such as business goals, etc, that kind of thing really belongs elsewhere, especially (depending on how you plan on deploying your application) considering that each checkout of your application code will be pulling down all this documentation unnecessarily (you certainly don't need it on the server, unless it's documentation about running server related maintenance scripts, etc).
Rails特别在Rails根目录中生成一个doc目录，看起来像是放置与应用程序相关的文档的地方。但是，您需要问自己，如果文档是独立的(而不是直接与该应用程序的源/开发相关)，您是否希望将其放置在同一个存储库中(假设您正在使用scm系统)。如果您正在编写的文档不是相关项目的开发,而是使用或其他目的,如业务目标,等等,这样的事情真的是在其他地方,尤其是(取决于你打算怎样部署您的应用程序)考虑到每个检查您的应用程序代码将向下拉这一切不必要的文档(你当然不需要在服务器上,除非是关于运行服务器相关维护脚本等的文档)。
If you are just writing simple text, then .txt makes sense for your extensions. But really, just use whatever files (and appropriate extensions thereof) that you and your team are comfortable with.
如果您只是编写简单的文本，那么.txt对于扩展是有意义的。但实际上，只要使用您和您的团队熟悉的任何文件(以及适当的扩展)。
Again, it really depends on the purpose of this documentation and who it is for. If it's not useful to the application developers or for deployment/management purposes, it doesn't really belong in the application at all and should either be stored in a separate repository or a dedicated system for sharing this documentation with the people that need to have it, be that a simple shared folder on a server somewhere or something more specialised.
同样，这也取决于这个文档的目的和它的用途。如果它不是有用的应用程序开发人员或部署/管理的目的,它并不属于应用程序,应该存储在一个单独的存储库或专用系统共享这些文档需要它的人,是一个简单的共享文件夹在服务器上某个地方或更专业的东西。
#3
0
Why not use the doc subdirectory and rake doc:app ?
为什么不使用doc子目录和rake doc:app呢?
#1
2
There is a folder called doc where you can put your documentation (only public is accessible anyway), README_FOR_APP is the place where to introduce your application and put notes for private users.
有一个叫做doc的文件夹，你可以把你的文档放在那里(只有公众可以访问)，README_FOR_APP是介绍你的应用程序的地方，并为私人用户提供笔记。
readme.rdoc or readme.md in the root folder is another great place for instructions and copyrights, if you have a look at some opensource project on github (devise) you'll see that this file is displayed by default under the project directory.
自述文件。rdoc或readme。根文件夹中的md是指令和版权的另一个好地方，如果您查看github上的某个opensource项目，您将看到该文件在项目目录下默认显示。
I stick with the doc folder for more specific documentation, I use a odt and ods for requirements and the default extension of BOUML for uml. TODO.TXT to remind me features to be implemented (and just the keyword TODO in the code for things to fix)
对于更具体的文档，我坚持使用doc文件夹，对需求使用odt和ods，对uml使用BOUML的默认扩展。待办事项。TXT来提醒我要实现的特性(以及需要修改的代码中的关键字TODO)
There is a plugin for documentation (yard) and I think they took good care of theirs.
有一个文档插件(yard)，我认为他们很好地照顾了他们。
If you don't want (and you don't) the doc on the production server remove it with your git configuration, we have two server, one local for development an external one for production.
如果您不想(而您不希望)生产服务器上的doc删除它与您的git配置，我们有两个服务器，一个本地的开发一个外部的生产。
EDIT If your documentation is subjected to frequent update from different users (especially at the beginning), you may prefer to have that folder synchronized with say ubuntu one or dropbox or even use something like google docs.
如果你的文档经常从不同的用户那里得到更新(特别是在开始的时候)，你可能更喜欢与ubuntu one或dropbox同步，或者甚至使用谷歌文档。
#2
1
Well, this isn't so much a rails question as a general project organisation question.
这与其说是一个rails问题，不如说是一个通用的项目组织问题。
Rails in particular generates a doc directory in the rails root directory which seems like the place to put documentation related to the application. However, you need to ask yourself whether or not you want to be placing the documentation, if it's standalone (rather than being directly related to the source/development of said application) in the same repository (assuming you are using an scm system). If the documentation you are writing isn't really related to the development of the project, but rather it's usage or some other purpose such as business goals, etc, that kind of thing really belongs elsewhere, especially (depending on how you plan on deploying your application) considering that each checkout of your application code will be pulling down all this documentation unnecessarily (you certainly don't need it on the server, unless it's documentation about running server related maintenance scripts, etc).
Rails特别在Rails根目录中生成一个doc目录，看起来像是放置与应用程序相关的文档的地方。但是，您需要问自己，如果文档是独立的(而不是直接与该应用程序的源/开发相关)，您是否希望将其放置在同一个存储库中(假设您正在使用scm系统)。如果您正在编写的文档不是相关项目的开发,而是使用或其他目的,如业务目标,等等,这样的事情真的是在其他地方,尤其是(取决于你打算怎样部署您的应用程序)考虑到每个检查您的应用程序代码将向下拉这一切不必要的文档(你当然不需要在服务器上,除非是关于运行服务器相关维护脚本等的文档)。
If you are just writing simple text, then .txt makes sense for your extensions. But really, just use whatever files (and appropriate extensions thereof) that you and your team are comfortable with.
如果您只是编写简单的文本，那么.txt对于扩展是有意义的。但实际上，只要使用您和您的团队熟悉的任何文件(以及适当的扩展)。
Again, it really depends on the purpose of this documentation and who it is for. If it's not useful to the application developers or for deployment/management purposes, it doesn't really belong in the application at all and should either be stored in a separate repository or a dedicated system for sharing this documentation with the people that need to have it, be that a simple shared folder on a server somewhere or something more specialised.
同样，这也取决于这个文档的目的和它的用途。如果它不是有用的应用程序开发人员或部署/管理的目的,它并不属于应用程序,应该存储在一个单独的存储库或专用系统共享这些文档需要它的人,是一个简单的共享文件夹在服务器上某个地方或更专业的东西。
#3
0
Why not use the doc subdirectory and rake doc:app ?
为什么不使用doc子目录和rake doc:app呢?