Although I use webgui for many years, I've just started to write my first few macro's these weeks. I  used to program, but I haven't programmed for years.

The first thing I needed to learn was to learn to search the api. Silly perhaps, but I knew perldoc (how to use it with -q) but I didn't know it could be used to extract the POD. I didn't know the word POD. Only hours after I discovered this, I returned to reading the code itself. Sorry, but the documentation is not always very enlighting. It's written more as a reminder than an explanation. Also the recursive use of grep was a life-saver. Next I discovered WebGUI::Utility, quite small, but handy. My biggest need right now would be a birds-eye view of webgui: the session hash, the definition subroutines, the major objects you (re-)create (user, specific assets, forms of course, handy things like newByDynamicClass). After I only discovered a little bit a strong longing to change things in WebGUI came over me. But since I've picked up some things from conversations of other people I transformed this longing in a longing to know how to make a development environment for myself.

Having changes accepted is the reward, but I know I need to make them in the current version. We don't have the latest beta in production of course and in your daily work for customers you discover your needs. How do I work with both our production version and the latest beta, how do I change environment. How do I combine the webgui subversion versions with my own? 

After that of course I need to know the policy. Although I've heard a lot of others I don't have a plausible intuition of what would be acceptable and what not and why. Why is the rss-from-parent - apart from the way in which it's coded - not a path to continue and why was the my-friends extention that I let Plainblack code no problem, where I was expecting it to be? 

If we have a goal in sight and know what we need to know to get the reward - have your own changes accepted in the core - we can go deeper. Zoom into the session hash for example. After simply outlining all the major parts of WebGUI's architecture, we're ready for the tips and tricks. The things you understand if you have a context. 

Don't make it into a book about PERL, make it into a book about WebGUI. Yet, do read Damian Conway. Because the way he writes and the way his books are structured are a great example I think. You can actually *read* his books from cover to cover, which is rare with technical books, that normally more invite you to use them as a reference. 

Also: think about the learning *process*. Sorry to be negative, but I've ordered WebGUI primer and the Content Managers guide, but I'm not going to order it for my clients. People have different needs in different phases of their learning process. First show an attractive possible result of what you can accomplish so people can image a goal, develop motivation. Then give them a first reward with something simple to do with amazing results. After that: give them background, a birds-eye view of what there is to learn. Then start with the core-concepts. Don't go in depth, let people read on. And only then you can continue in a way the content managers guide is written. Only then people have the background to start using their imaginaton. And: don't forget the community and the habits ('culture') in it. Ok, it's not a custom to copy-past PERL code in irc, I didn't know there were things like pastebot. Give people learn-to-learn ability. That's what I needed anyway. And still need in many ways. 

Some examples: 1. Often I am not able to make forms the way I want. Often they are not XHTML compliant, for example no space and /> at the end. I would very much be able to do just that. I guess this is something desirable, but nevertheless: I don't know how I should start and what path is the right path. Should I make more template variables available, so people can make their own tags, with their own id's in them. Or should I document the id's used and simply make the template variables that don't produce valid XHTML1.- strict compliant. 2. I've discovered a serious problem in the navigation (I did) I don't have any clue what the problem is, it's hard to explain and quite some work to recreate. Where do I go? The dev-forum, irc or should I first learn to understand my problem in the etcetera-forum? Is that forum read by people who could actually understand the problem?

After re-reading this: I think my biggest needs are twofold: 1) policy, habits, culture and how to develop a plausible intuiton for it and 2) from concepts to practical use. And don't forget the concept-part. For most of the practical use part your remark is true: developers are probably resourceful enough to find the details out themselves. 

I - personally - would very much like Plainblack to make a developers' guide, but I don't expect you to make a lot of money with it. I agree, the wiki is great. Many things can be explained in the wiki. But a book is something else. It has a different structure, a beginning and an end.  I do think it's good for the size of WebGUI's developers base, it's status - there are books about Plone, Typo3, PHPNuke, but not about WebGUI - and things like that. But the amount of books you sell will probably be small, while if the content managers guide would be really good, I would not only buy it myself, but give it to every customer. 

Kind regards,

Arjan.