Where and what I have to do to document my Ruby on Rails application? [closed]

Closed. This question needs to be more focused. It is not currently accepting answers.

---

Want to improve this question? Update the question so it focuses on one problem only by editing this post.

Closed 5 years ago.

Improve this question 开发者_JS百科

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.

But I have some questions/doubts:

1. Where (in which folder of the RoR application) I must create documentation files?

   Notice: I would like to allow only developers to view these files. No pubblic access.

2. What file extension do you recommend to use?

   Notice: in documentation I have to insert simple text.

3. Have you any general recommendation to do about this topic?

   Example: is it a wrong approach?

---

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.

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.

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)

There is a plugin for documentation (yard) and I think they took good care of theirs.

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.

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.

---

Well, this isn't so much a rails question as a general project organisation question.

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).

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.

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.

---

Why not use the doc subdirectory and rake doc:app ?