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
Initial read up of a certain section (getting to know all the important stuff of a certain component/functionality).
"Getting the big picture"
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):
- 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.
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".
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!