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 for documentation. 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 the documentation. > > We've hashed out what we think would be a better structure, but since > the community uses the documentation far more than we do, we want your > opinions on how a new book should be structured. > > https://github.com/markstory/cakebook-experiment/wiki/alternate-structure > > 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 the documentation structure. 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. -- 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
