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 out that there are _numerous_ documentation sets that have no comments, and they seem to service their communities perfectly well. 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 -- 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
