Suggestions for Improving the Cookbook Structure

[Simon]

[Apologies if this should be submitted as a ticket instead, but I
wanted to get some discussion first.]

Hi. I'm fairly new to the CakePHP community, but that probably gives
me a unique perspective on the Cookbook documentation. I have some
ideas for restructuring the cookbook to make it easier for beginners
to get started, and also for experts to locate the relevant sections.
I'd love to contribute to some of the sections where I can, but the
organisation already has me a little frustrated.

Basically I think the content should be in this rough order:

- Overview
- Installation
- Getting a basic site running easily
- Advanced techniques

If people find it easy to get a basic site running they'll be more
willing to explore the extra features. I also think that many of the
sections should be combined onto one page so that you don't have pages
with only a single paragraph (it takes too long to page through
sections like that).

Below is a rough idea of how I think the Cookbook could be
structured. Not everything has been included (its a draft) but notice
how the sections are named with helpful titles like...
"Using Bake to quickly generate code" vs "The Bake Console"
"Displaying messages to the user" vs "Flash"

Simon.
me(at)simoneast.net

======================================

CakePHP Overview
-- Introduction
-- Top Ten Reasons to Use Cake
-- List of Features
-- System Requirements
-- Programming Knowledge Required

Getting Started
-- HTTP server setup
-- -- Activating mod_rewrite
-- CakePHP files, testing if it works
-- Your database
-- -- Database engines
-- -- Database structure
-- Creating models for your data
-- Get running quickly with scaffolding
-- Using Bake to quickly generate code
-- Changing layout and appearance using Views & Layouts
-- Displaying messages to the user
-- Getting More Help

Developing with CakePHP
-- The Model-View-Controller Concept
-- Typical CakePHP Request
-- Configuration Options
-- File Structure
-- Programming Conventions
-- Models (The Data Layer)
-- -- Validating Data
-- -- Custom Functions (e.g. calculating a total price for an item)
-- Controllers (The Action/Behaviour Layer)
-- -- Components
-- -- -- Core Cake Components
-- Views (The Presentation Layer)
-- -- Layouts
-- -- Using CSS and Javascript
-- -- -- Tips on where to place these files, how to reference these
files in views, and how to reference other files from within CSS/
Javascript
-- -- Working with Static Pages
-- -- Sanitising Data
-- -- Elements
-- -- Helpers
-- -- -- Core Helpers
-- -- Internationalisation and Other Languages
-- -- Custom Error Messages
-- Custom URLs using Routing
-- Security
-- -- Include overview of all security issues, perhaps linking to
different parts of cookbook
-- Behaviours
-- -- Core Behaviours
-- Improving Performance with Caching
-- CakePHP Console
-- -- Core Console Applications
-- -- Bake
-- Plugins
-- Testing Your Application

Common Tasks with CakePHP

Tutorials and Examples

Upgrading Cake

[John David Anderson]

On Apr 15, 2009, at 1:41 AM, Simon wrote:

> <snip>

>
> - Overview
> - Installation
> - Getting a basic site running easily
> - Advanced techniques

This is more or less how it's already organized, with the exception of
the "basic site" section. I think the first hurdle there is what
exactly constitutes a "basic site."

- Beginning with CakePHP (Overview)
- Basic Principles of CakePHP (Overview)
- Developing with CakePHP (Installation & requirements covered first,
then on to basics)
- Common Tasks and Core Classes (Advanced Techniques)

We also include the Blog example in the appendix, which most people
are pointed to even before they read the introductory materials.

>
> If people find it easy to get a basic site running they'll be more
> willing to explore the extra features. I also think that many of the
> sections should be combined onto one page so that you don't have pages
> with only a single paragraph (it takes too long to page through
> sections like that).
>
> Below is a rough idea of how I think the Cookbook could be
> structured. Not everything has been included (its a draft) but notice
> how the sections are named with helpful titles like...
> "Using Bake to quickly generate code" vs "The Bake Console"
> "Displaying messages to the user" vs "Flash"

I think before we're going to be able to entertain a complete
restructure, I'd like your input on how we could adjust the existing
structure first.

-- John

[Simon East]

Hi John, thanks for replying.

I think before we're going to be able to entertain a complete  
restructure, I'd like your input on how we could adjust the existing  
structure first.

Yes, fair suggestion.  I guess a good question to start with is: how easy is it to rename or combine sections without destroying links?  Will a URL to a particular section still work if (a) the title is renamed, or (b) if it's moved to become a sub-section of another page?  That issue may need to be resolved before any changes are made.

Following that, the first changes I would suggest would be tweaks to a few chapter titles to make it easier to understand what it might contain (or javascript expandable menus would accomplish a similar thing). 

Secondly I think some sections need combining so they display on a single page.  Perhaps a very rough guideline would be that if a section fits within one screen without scrolling (on a standard monitor) then it could perhaps be combined with others around it.  I would probably prefer Cookbook pages to be between 2 and 8 screenfuls on a standard monitor (depending on the depth and technical level).  What do others think about that?  Do you have a preference?  I think the structure and page length of the PHP documentation is a good example.

Would love any others to offer their opinions.

Thanks,
Simon East

[AD7six]

Hi Simon,

On Apr 16, 10:09 am, Simon East <m...@simoneast.net> wrote:
> Hi John, thanks for replying.
>
> > I think before we're going to be able to entertain a complete  
> > restructure, I'd like your input on how we could adjust the existing  
> > structure first.
>
> Yes, fair suggestion.  I guess a good question to start with is: how
> easy is it to rename or combine sections without destroying links?  Will
> a URL to a particular section still work if (a) the title is renamed, or
> (b) if it's moved to become a sub-section of another page?  That issue
> may need to be resolved before any changes are made.

renaming or moving things doesn't affect links working or not. Yes and
yes.

>
> Following that, the first changes I would suggest would be tweaks to a
> few chapter titles to make it easier to understand what it might contain
> (or javascript expandable menus would accomplish a similar thing).

Feel free to edit titles.

> Secondly I think some sections need combining so they display on a
> single page.  Perhaps a very rough guideline would be that if a section
> fits within one screen without scrolling (on a standard monitor) then it
> could perhaps be combined with others around it.  I would probably
> prefer Cookbook pages to be between 2 and 8 screenfuls on a standard
> monitor (depending on the depth and technical level).  What do others
> think about that?  Do you have a preference?  I think the structure and

> page length of the PHP documentation <http://www.php.net/manual/en/> is
> a good example.

It's not necessary (or advised) to combine sections to achieve that,
e.g.

http://book.cakephp.org/view/9/Where-to-Get-Help everything explicitly
marked (by an admin user) to show inline.
http://book.cakephp.org/view/467/Defining-Permissions-Cake-s-Database-ACL
already at the maximum depth, so all children + grand children shown
inline.

hth,

AD

[Simon East]

OK, I will look at making some tweaks to section titles and content.  As for displaying certain sections inline, perhaps I could post suggestions here for admins to look at?

I've been thinking through my theory, and I think what the Cookbook needs is an introductory section that allows newcomers to come and have a peek at CakePHP, get it running quickly, have a little play and decide if it will meet their needs for a project.  If they have to wade through too much documentation for that to happen, there's a chance we'll lose them.  The intro should provide just enough information to put them on the right track, but not too much to overwhelm.  More details can be expounded in later chapters.

Take a look at the "Getting Started with Rails" guide.  I think it does a reasonable job, although it seems a little wordy:
http://guides.rubyonrails.org/getting_started.html

I'd love to help get that introductory section working well if I can.  Does anyone else agree/disagree with that concept?

Simon.

[José Lorenzo]

I would totally agree, the reason I got into cake was because a little introductory article about cakekphp in sitepoint. It was enough for me to start reading the manual in that time.