I think I made this point a couple of years ago. I'm too lazy to go and try to dig up the thread. Here's my 10 cents.
I agree strongly that the current manual tries to be both introductory tutorial and reference. I also agree it's been hugely improved since v1 and is extremely useful. The cookbook should also prove to be a valuable resource. However, as a rare divergence in opinion from Massimo's, I strongly DISAGREE that we need a second, more introductory manual. Instead, I think we need a very concise, very dense reference manual. Here's my rationale. Although the v2 and v3 manuals have been made searchable online, the information about certain commands is still spread out all over the place. The way the manual works, it takes a long time to download, the TOC of each chapter to render, and then for the search to paginate you to the appropriate place in the doc. That's cumbersome, but it works IF you know what to search for. There is no index. And even if you do have the right search term, you often end up having to look in multiple chapters. In some cases, there's a lot of verbiage to consume as well. I suggest we, as a community, invest time in a unix-like man page or python-like doc reference. Each command of web2py to be listed, one to a "page". Each command should have its complete signature described in gory detail. In cases like Auth, there needs to be a complete listing and description of its many class variables. There absolutely has to be a cross-linked index, which should be the primary point of entry into the document. The reference should be searchable as well. Each web2py command/helper/whatever needs to have a short example. One thing I don't like about python doc is that it's extremely slim on examples vs. unix manuals, which have always had some short example or two. I think web2py has enough tutorial material for the time being. I'm not saying it can't be improved. But if we split out a reference, it will make tutorials easier to create in the future. Tutorials could then be more task-directed, like the cookbook. And whenever a new command or thingie gets added to web2py it can be easily added to the reference.
