ORM doc: 2.x task related structure is more accessible than 3.x object based

[Schlaefer]

I'm making myself familiar with CakePHP 3.0 at the moment. The 3.0 model docs are structured:

- Models

  - Query Builder

  - Table Objects

  - Entities

which documents everything nicely and is fine for a thorough read from start to end. But after using it for a day I find the 2.x task based structure much more accessible in constant use, which emphasizes what a user actually wants to achieve:

- Models

  - Associations: Linking Models Together

  - Retrieving Your Data

  - Saving Your Data

  - Deleting Data

Maybe something worth to consider, maybe it's just me.

Sebastian

[Jose Diaz-Gonzalez]

I definitely agree. I also think the docs - in general - have tended towards the verbose (in order to clear up things with certain segments of users) and I think they could use a whole-scale cleanup. Would you be willing to redo the 3.x model docs in a more readable structure?

--
You received this message because you are subscribed to the Google Groups "cakephp-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cakephp-core...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[mark_story]

All the sections you listed are in the current docs as well. However, they are one level lower, under table objects. Organizing documentation is really hard, as there are several audiences with differing needs. With the more recent chapters in the docs we've been trying to add more code samples, and include headings that make scanning easier. Both of these were common complaints regarding the 2.x documentation.

I am totally open for alternative ways we can organize the documentation to better suit the intermediate/advanced reader.

-mark

[Ravage84]

I think "one level lover" is already one too far...
That's also the reason why we have such extremly long pages.
And I think this is not a good thing to have.
I would prefer to see more but shorter pages.

Why? Because I know many people including me will lookup things like saving entities far more than once.
And navigating to a third level title like the one below - each time - is not fun.
http://book.cakephp.org/3.0/en/orm/table-objects.html#saving-entities

Sure, the search is there to ease this up, but it's not always helpful.
For example if you don't know the right words to search for.

There are different use cases for documentation like this
1. Manual:
Initial read up of a certain section (getting to know all the important stuff of a certain component/functionality).
"Getting the big picture"
2. Reference:
Looking up some specific information.
"Getting the answer to a question"

I guess something in the middle of many short pages and very few long pages could work for us.
Task based titles/pages better work for the initial read up, while reference pages will be used by more advanced CakePHP users.

Let's say we have these pages (categorisation in brackets):

- Models
  - Associations: Linking Models Together [Basics] [Manual]
  - Retrieving Your Data [Basics] [Manual]
  - Saving Your Data [Basics] [Manual]
  - Deleting Data [Basics] [Manual]
  - Query Builder [Advanced] [Reference]
  - Table Objects [Advanced] [Reference]
  - Entities [Advanced] [Reference]
  - Behaviors [Advanced] [Reference]
  - Database Basics [Advanced] [Reference]
  - Schema System [Advanced] [Reference]
  - ORM Cache Shell [Advanced] [Reference]

As you can see at the top we have mostly stuff that would interest the newbies, that will be lookup up often.
The more advanced reference stuff is more below.

If I'm a total newbie to CakePHP 3.x and have no idea yet, I want to be led to my answer (by titles).
So, I know the information I have to learn about is about getting data out of the database. I know I have t use the model layer.
So it is only natural to navigate to Models -> Retrieving Your Data.
Done.

But if I'm more advanced with CakePHP 3.x and have a very specific question - let's say about how to add table options in the schema - in mind, I tend to know what specific class to use and I am willing to look it up.
So I navigate to Models.
I see "Schema System".
Makes sense, open it.
Then I browse through the titles on the left, find "Adding Table Options".
Done.

It's no wonder the current (model) documentation is so class centric.
Mostly Mark and Lorenzo have written it while working actively on the new ORM for months.
So each time they implemented a new feature in a class, they added the new information under Models->[class name/logical component] instead of  trying to have the common task in mind.
Don't get me wrong, this is no criticism!

Marc

[mark_story]

One level lower may be a problem, but shallow wide navigation systems are not without their faults. I will admit that the current 3.x sidebar topic heading under models is not as clear as it was in 2.x.

One reason the orm docs are written the way they are is that I find big long pages easier to scan through and search with cmd-f. I can totally understand that not everyone will have the same workflows and am up for restructuring the ORM docs if someone can propose a section order that they think will make sense to a broader audience.

The tension between guide and reference is a really hard one I find. I've definitely struggled with this in the past. I think mine & jose's current plan around this is to have book.cakephp.org function as a guide and light reference, while more of the 'reference' style documentation should really be in the API as enumerating all the options for every class and every method is a waste of space in the book. To be fair, the API docs are probably not as good as they should be in the reference department.

-Mark

[Schlaefer]

I'm also in the cmd+f camp, so I don't have a problem with long pages per se. My main discomfort at the moment is that actions are scattered over multiple pages, so I have to cmd+F on Query, Table and Entity pages to find out about all possibilities to read or store data.

My preferred structure would be along those lines:

- Models
  - Database Basics

  - Query Builder
  - Table Objects
  - Entities

  - Retrieving Your Data & Result Sets

  - Saving Your Data
  - Deleting Data

  - Associations: Linking Models Together
  

  - Behaviors
  - Schema System
  - ORM Cache Shell


First learn about how databases are handled in CakePHP and the objets involved, what is their purpose and how do they relate/interact with each other (Query, Table, Entity). You'll probably read this once. 

After that come pages describing the basic methods/tasks (read, create/update, delete) and getting things done using them. This is a reference heavy area.

Then go into advance topics working with the ORM (associations)  followed by additional Cake facilities (Behavior, Schema, Shell).

[mark_story]

Schlafer: That proposed topic order sounds like an improvement to me. Would you be able to help make the change?

-mark

[Schlaefer]

On Saturday, November 29, 2014 11:27:50 PM UTC+1, mark_story wrote:

Schlafer: That proposed topic order sounds like an improvement to me. Would you be able to help make the change?

I'll fork, shuffle things around and see how it will play out. Alas english is only my 3rd language, so if much glue text is necessary I may cop out. ;)