The documentation is very well done but has a few areas that could use improvement.
The self-help diagnosis centre is a great idea. And I agree 100% that documentation on Ajax and Acl needs to be improved. Is anybody working on this? I am willing to lend a hand or even get this started. Sent from my BlackBerry device on the Rogers Wireless Network -----Original Message----- From: Jeremy Burns | Class Outfit <[email protected]> Sender: [email protected] Date: Fri, 18 Mar 2011 05:45:54 To: <[email protected]> Reply-To: [email protected] Subject: Re: Documentation changes Sort of related to cricket's points, but I'd like to see the validation section moved nearer to the model, rather than in a 'common tasks' section (I couldn't see any reference to either validation or common tasks in the proposed structure). Pleased common tasks has gone - it's contents ought to be in the main body; a search will always show them anyway. I know you've only presented a tree and no indication of text quality/quantity, so this might be premature. There are a couple of chestnuts that always come up on the forum; ajax/js and ACL. I wonder if it is worth adding some hearty text about them too? I think it is often acknowledged that the section on the Js helper is a bit thin at present (also pleased to see the Ajax and JavaScript helpers have gone - they are confusing still being in the 1.3 doc when they have been deprecated). Another suggestion I'd make is some sort of self-help diagnosis centre (are the files spelled correctly, have you stuck to conventions, do you have mod_rewrite etc) and a flow chart that shows the order in which code is processed (this file, then this action, then this callback etc). Thanks Mark & team. Great work. Can't wait to start using 2.0. Jeremy Burns Class Outfit [email protected] http://www.classoutfit.com On 18 Mar 2011, at 01:05, mark_story wrote: > On Mar 12, 3:58 pm, cricket <[email protected]> wrote: >> On Sat, Mar 12, 2011 at 12:48 PM, mark_story <[email protected]> wrote: >>> In the 1.3.7 release announcement, we announced the possible move to >>> sphinx + git fordocumentation. The following experiments have turned >>> up promising results, and the temporary repository contains functional >>> documentation, that still needs some improvement. >> >>> One of the improvements that needs to occur is a restructuring of the >>> documentation. The current structure of the cookbook, often confuses >>> both new and experienced developers, as its not the most logical or >>> best planned layout for thedocumentation. >> >>> We've hashed out what we think would be a better structure, but since >>> the community uses thedocumentationfar more than we do, we want your >>> opinions on how a new book should be structured. >> >>> https://github.com/markstory/cakebook-experiment/wiki/alternate-struc... >> >>> If you have the time look over the above link, and reply with any >>> comments or alarm bells about this structure, or any glaring omissions >>> that should be included. >> >> Thanks, Mark. My $0.02: >> >> I think it would be much better to put core components, helpers, and >> behaviors in their respective sections instead of later, in the "Core >> Libraries" section. It's the logical place to look them up, as well as >> to introduce them right after explaining what a component, helper, or >> behavior is. >> >> That's abou it. In all this looks like a really big improvement for >> thedocumentationstructure. >> >> One other thing, although it's not a point about the structure. Make >> sure that it's more obvious why 404s can happen when debug == 0. So >> many people trip up on this. It's a great idea but it's not at all >> obvious (which is the point, of course). And Cake has this mysterious >> routing thing (not to mention mod_rewrite being involved), so a lot of >> new users go chasing down that path (heh) instead of looking for the >> error in their code. I'm not sure what the text should read but it >> should be repeated in several prominent places in the book, IMHO. > > Thanks for the feedback Cricket. I was planning on mostly re-writing > the error handling docs as most of the behaviour has changed for 2.0. > Including information on how 404's can be triggered is a good idea as > well. > > -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 -- 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 -- 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
