From: Michal Suchanek Date: 2009-10-07T08:03:24+09:00 Subject: Re: Ruby for the wrong reason 2009/10/7 Stefan Peters : > > > On 6 Okt., 23:15, Michal Suchanek wrote: >> 2009/10/6 James Edward Gray II : >> >> > On Oct 6, 2009, at 1:59 PM, 7stud -- wrote: >> >> >> I have suggested a better solution in the past, and I'll suggest it >> >> again: open up the ruby docs to user comments like php does.  If the >> >> ruby community wants to continue with the worst docs I've ever seen, >> >> then so be it. >> >> > Well, they Ruby Core team does take patches. >> >> It's not the same thing. >> >> You can comment on the PHP documentation even if you don't know how to >> make a patch and don't understand whatever format the docs are in. >> Still people visiting the documentation site can read the comment. >> >> It has its downsides, too. There are some meaningless comments or >> multiple refinements of the same sample code. > > > And lots of really bad/wrong/dangerous code (that is often c&p). I Of course, the quality of the code posted as part of the comments varies but if there is a common pitfall that is posted it is more likely that somebody finds out and posts a correction before you look than that you would not hit the same problem if you put together the code yourself. It seems to me that in PHP language-specific pitfalls are notoriously created by language misfeatures. The weakness of PHP is it does not have irb so clarifying the description for yourself is quite expensive. Still a missing reference like the one with strftime format may not be easy to find and could be added as a comment. One of the other problems is that as any public forum you not only need an infrastructure for collecting a and storing posts but also a human moderator(s) to watch over the system. > dont think that comments are a good idea, but may be some kind of wiki > would be productive, because I also think, that the documentation > needs improvement. > The strength of the comments is that they are right below the description. A separate wiki would likely die a quiet (or spammy) death. I would guess it's even less likely to succeed than posting a doc patch. Thanks Michal