On Jan 21, 1:12 pm, 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?
Would you mind pointing at any comment you've seen in the book that you consider appropriate? AD -- 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
