However, while we're finalizing the decision on which direction to take, I've put together a 'pilot chapter', i.e., a chapter of my personal take on how the content and flow of a chapter in the book could/should be. In my mind, the book should be very heavy on examples and code. It should cover everything that could possibly be covered in whatever area is being covered. Someone should be able to pick up the book, think "Hmmm. I wonder how code completion works," and then find everything on code completion in the book. So, in my mind, the focus should be on practical, sample-based texts.
Plus, everything should be interesting and readable, with screenshots, tips, and interesting bits of information scattered around, much like the NetBeans IDE Field Guide. My other great example, in the API documentation area, is the OpenOffice.org Developers Guide, which is fantastic.
So, the pilot chapter is reaching completion and is attached below. It is about the WebFrameworkProvider class, which any module developer interested in integrating a web framework (Tapestry, Spring, etc) needs to know about (before knowing about anything else). Here are some questions to ponder while browsing/reading the chapter:
Don't worry about the font or the quality of the screenshots. Also don't worry too much about the technical detail. There are some gaps, but not many. (In fact, you should be able to pick it up already and have enough information for integrating your own framework.) Still, the chapter needs to be technically reviewed, so don't be surprised if you find some problems here and there (which I'd appreciate being told about).
One important question—do you see the user (i.e. you) going through the chapter step by step implementing the examples in the chapter, or is it more likely that the user would have (in this case) their own framework in mind and use the chapter as a guide when implementing their own framework? (In other words, would people use it as a tutorial to follow religiously or as a frame of reference?) Another question—does it make sense to focus on just one framework from beginning of the chapter to the end (and, if so, which one)? Or does the current situation, where a variety of frameworks are discussed, appeal more to you?
By the way, I imagine there'd be a CD with code samples, which would be referred to in the chapters themselves, where applicable.
Apologies, but I haven't been able to work out how to do internal hyperlinks (called 'bookmarks', I think) in Open Office, so the table of contents doesn't link to the individual sections. Here it is:
Feel free to either leave comments on this chapter in this blog or to send them to me personally. Remember—your input will turn this book into what you need. No input from you might result in a book which you will not find helpful!