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 -- 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
