Em 13-09-2009 01:35, Xavier Noria escreveu: >> Docrails will eventually be outdated, since it is a separated project >> and it is always behind main development. >> > > I don't really know what you mean here. > > docrails is a branch. The Rails Documentation Team are *not* the > documenters of Rails, we are the guys that have an eye in that area of > the project, just that. >
That is exactly what I meant. I was not complaining. But since the guides documentation are not an official documentation, there are no concerns in updating the guides when something changes in source-code in the same patch. I guess most core developers didn't even read all guides so that they are aware of changes that possible affect the guides. The consequences are that the guides will eventually be outdated until someone notes and updates its documentation to reflect the new changes. This is a bit dangerous in my opinion if we want to welcome new developers. Documentation is one of the most important roles in any framework. Once the user is not able to follow the instructions in the recommended source of documentation, he/she might get a bad impression on the framework consistency and organization. Where I work currently, I am asked to develop in Grails. The documentation are most contradictory or incomplete. This really makes it very difficult not only for newcomers but for long date users too. The documentation states that some magic variables need to be declared in some way in the controllers under documentation, while the scaffold generator uses another way to declare the same behavior. Both documentation and framework version refer to the same version (1.1.1) but they are inconsistent. This happens a lot in Grails. When one tries to convince some company to adopt Rails, it will be more difficult if the documentation is not clear or is incorrect. In the other side, if we low the learning curve to new developers and make the documentation consistent, we will also get more contributors to help us getting Rails better and better faster. In my specific case, if I could convince the Rails team to accept a patch to include the :full_message option to validations, it would be easier to make a clean presentation of Rails framework to my company and try to convince them to accept Rails... In Brazil, at least, the default full_messages behavior is not that much useful for real applications. We are very concerned, in our company at least, to give users well formed Brazilian messages. Brazilian phrases usually initiate with an article, instead of the model attribute. In some cases, it makes more sense that the attribute come at the end of the phrase, and some times the attribute itself is not even cited in the message. Having to patch around I18n files will not make any sense in a presentation and it would make it seem very difficult to do simple things in Rails. Imagine this scenario: validates_presence_of :login, :full_message => 'You must specify an user name.' validates_format_of :login, :with => /[a-z]+/, allow_blank => true, :full_message => 'Your user name should contain only small case letters' Pretty simple to get it, don't you think? But since :full_message doesn't exist, it would be much more confuse if I told them that to get these messages as of today, I would need to explain them how i18n works in Rails, even if they don't care about i18n, since the product is not intended to be commercialized outside Brazil, and they hardly would think that control of the full message should be related to i18n. And even showing them how to achieve this same result with i18n framework it would indeed be much more confusing than the above clear examples. I am always concerned about new adopters and trying to get their experiences as smooth as possible. Regarding Rails, it usually means investing in documentation. But in this specific case of full messages control, I would prefer to submit a patch, that would still be compatible with how it currently works. I would just add an extra option to validations. > Sure, we do a lot of work on the API, but the Rails documentation > comes from patches to master. If a patch is not properly documented it > should not be accepted as if it hadn't tests. > > You know docrails and master are cross merged regularly, there's no > way it can become outdated because docrails works directly against the > Rails repo. > Yes, I was not clear in my last message. You are talking about API documentation and I agree with you. I was talking with Rails guides in mind. > It has its own branch to be able to offer an open policy with a little > safety net and strict rules about not touching code. With the purpose > of agilizing doc patches that should go the LH way and good luck > otherwise. > > We're doing the guides as well. We commented with Pratik and Mike that > code patches should patch guides, but that is not being enforced in > practice. > Exactly. I agree with you. It would be awesome if the guides updates were enforced in practice, but I can understand their reasoning that it would slow down main development... I really don't know what would be the best approach to this problem by now... > As per verisioning, docrails always documents edge, both in API an > guides. If you want the docs of a release you take its snapshot > (guides are included in Rails releases). The public websites only have > stable and edge. > Yes, I know that, and I really don't see any problems in how it is done. I really think the docrails project is an excelent idea, as it is. I was just trying to integrate it more with core development in such a way that the guides would not be outdated... Congratulations for your work in docrails, by the way. Cheers, Rodrigo. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Ruby on Rails: Core" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/rubyonrails-core?hl=en -~----------~----~----~----~------~----~------~--~---
