I've started work on converting the documentation into the format sphinx uses, as well as updating the content for 2.0. If you want to help you can fork the repository and make the changes you'd like to see.
https://github.com/markstory/cakebook-experiment is the url for the repo, it will soon move into the official CakePHP github account, as the feedback so far has been pretty good. -Mark On Mar 20, 10:45 am, [email protected] wrote: > 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 > > Tutorialshttp://tv.cakephp.org > > Check out the new CakePHP Questions sitehttp://ask.cakephp.organd help > > others with their CakePHP related questions. > > > To unsubscribe from this group, send email to > > [email protected] For more options, visit this group > > athttp://groups.google.com/group/cake-php > > -- > Our newest site for the community: CakePHP Video > Tutorialshttp://tv.cakephp.org > Check out the new CakePHP Questions sitehttp://ask.cakephp.organd help others > with their CakePHP related questions. > > To unsubscribe from this group, send email to > [email protected] For more options, visit this group > athttp://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
