On Jan 22, 12:23 am, mark_story <[email protected]> wrote: > On Jan 21, 7:12 am, NdJ <[email protected]> wrote: > > > Hi Mark - loads and loads of kudos for the ever continuing progress of > > CakePHP - it's a framework I enjoy immensely. > > > Following on with the comments about comments for documentation:- > > > > > > Leave a comment with your thoughts on the proposed documentation > > > > > changes. > > > > > Ability to download in other formats is important, agreed. > > > > > Does Sphinx support the ability to do the following (as we have in the > > > > current cookbook, but I don't see in the Python /Django docs): > > > > > - ability for users to comment on the sections? > > > > I hate to say this in public, but the comments on the book have not > > > been successful in my eyes. They are filled with incorrect > > > information, misleading information and content that should have been > > > edits instead. > > > Ouch (well kinda) > > > User contributed comments are a double edged sword I have no doubt, > > comments get made, they may be wrong and no one really has time to > > monitor or catch errors and poorly crafted code suggestions. > > > On the flip side, user comments are routinely a valuable resource when > > trying to work stuff out. Consider what many of us do when facing a > > particular problem, we Google it to see if "someone" out there has > > already solved the given problem or something related to it. If you > > can't find a ready built piece of code you may often find hints, ideas > > and techniques that set you off on your way. > > > Consider two examples where comments work very well and are > > particularly powerful:- > > *http://php.net/manual/en > > *http://dev.mysql.com/doc/refman/5.5/en/ > > > Are they perfect? No. Are they enormously helpful, very often yes! > > > I doubt there is any perfect solution when it comes to API/Framework > > documentation like this, but loosing an _easy_ and _central_ place to > > communicate and share ideas with others about methods and functions > > feels like a terrible thing to loose - it's such fertile ground... > > > Is there a way we can continue the search for a documentation setup > > for CakePHP that includes comments? > > > Regards, > > NdJ > > Comments are a fertile ground, and sometimes they are fertile for > infestation of incorrect information. Unfortunately, the large bulk > of comments in the book are this kind. It pains me to say that, as > originally the hope was that they would be as useful as the comments > on php.net. But sadly it just never happened. I'd also like to point
That's a real pain. I can imagine the head-twist it puts on the dedicated individuals who go to enormous efforts to create documentation in the first place. To see comments attached to their documentation that might be wrong, misleading or perhaps even nasty is not at all enjoyable. Not to mention the time sink. Uck! > out that there are _numerous_ documentation sets that have no > comments, and they seem to service their communities perfectly well. Yes, fair enough - RubyDoc is a great example of this. For me though, the fact that RubyDoc does not have comments drives me crazy and I'm forever Googling elsewhere to find people talking about stuff to discover more information. I'm guessing I'm not the only one doing this (I could be wrong!) > By we, I hope you mean you. If you feel the current suggestion is not > up to snuff, then please suggest a better one. Using sphinx doesn't > occlude the possibility of using disqus for comments. jQuery does > this for their documentation and it works. > > -Mark Never realized the comments at jQuery were driven with Disqus, I like the comments setup there, it's not dis-similar than php.net or dev.mysql.com. So yes, implementing comments in that manner seems like it would answer the call for comments functionality quite well. It also follows on with the theme of outsourcing non-core effort reducing the time sink. My bad, using the word "we" in my earlier comment I did not mean to imply ownership. Can I suggest something better than the Disqus approach? Probably not. Disqus certainly looks to be very quick to implement and shifts the burden of feature maintenance off your plate, not sure how you could do better. Regards, NdJ -- Our newest site for the community: CakePHP Video Tutorials http://tv.cakephp.org Check out the new CakePHP Questions site http://ask.cakephp.org and help others with their CakePHP related questions. To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/cake-php
