what about wiki.rubyonrails.org ?
Sarah Allen
We had a RailsBridge meetup at RubyConf. One of the things we talked about is the install instructions that Sarah Mei and many volunteers maintain [1] in support of the workshops. Someone asked why we don't host it on the rubyonrails wiki and couldn't RailsBridge do something about how out of date it is?
When I first learned Rails a couple of years ago, I sometimes stumbled upon that wiki and typically saw it was out of date and assumed that it was obsoleted by the Rails Guides. Could you all who are more acquainted with Rails history and perhaps involved in core documentation efforts give some guidance as to whether it would be a good thing if the wiki were updated and how that content relates to the Rails Guides and other resources?
Note: I don't personally have a lot of time, but periodically run into other people who ask me what they can do to help.
Thanks,
Sarah
[1] http://www.wiki.devchix.com/index.php?title=Workshop_Installation_Notes_Rails_3
Xavier Noria
> We had a RailsBridge meetup at RubyConf. One of the things we talked about is the install instructions that Sarah Mei and many volunteers maintain [1] in support of the workshops. Someone asked why we don't host it on the rubyonrails wiki and couldn't RailsBridge do something about how out of date it is?
>
> When I first learned Rails a couple of years ago, I sometimes stumbled upon that wiki and typically saw it was out of date and assumed that it was obsoleted by the Rails Guides. Could you all who are more acquainted with Rails history and perhaps involved in core documentation efforts give some guidance as to whether it would be a good thing if the wiki were updated and how that content relates to the Rails Guides and other resources?
Hi Sarah,
I am not a big fan of wikis. The main problem with wikis in my
experience is maintenance. Also they normally lack editorial quality,
consistency, etc.
I think Rails has consolidated two sets of documentation:
* Guides for learning
* API for reference
Maintenance of these ones is easier because they are part of the Rails
repo. So, if a patch renames a method, say, the author has the means
to update the code, update the test suite, and update the
documentation. That includes grepping the entire tree looking for
occurrences in any example anywhere. Revising idioms in examples, etc.
Besides, this way we are in control and can ask for better
documentation coverage in LH if a patch is incomplete in that regard.
We are doing that more and more, and I hope that this becomes as
strict as with test coverage.
Then, since everything goes through Rails, we can ensure new docs
adhere to the API and guides guidelines, with some occasional
copy-editing.
All in all, I think it is better for Rails to be strong and clearly
focused in those two sets of documentation.
I personally believe updating the wiki is not worth the effort.
Brian Hogan
All in all, I think it is better for Rails to be strong and clearly
focused in those two sets of documentation.
I personally believe updating the wiki is not worth the effort.