Friday September 08, 2006
Friday September 08, 2006
Pilot Chapter for Upcoming NetBeans Module Development Book
We're talking about writing a book for the module development area. There's still some discussion about whether the book will primarily focus on module developers or on NetBeans Platform developers, but the general line of thinking seems to (currently) be in favor of creating a module development book. (Of course, the other could be written at some future stage, plus there's a lot of overlap between the two areas, so NetBeans Platform applications will inevitably be discussed to some extent.)
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:
- Is it interesting?
- Is it readable?
- Is the style conversational? If yes, is that good? If no, how should it be different?
- Is it practical? (Could you see yourself picking it up and doing something with it?)
- Is it the right level of detail?
- Is it too simplistic? Should it be pitched at some 'higher level'? (And define what that is.)
- Does it cover everything needed in this area? (If not, what's left out?)
- Enough screenshots? More needed?
- Too much code?
- Like the tip lightbulb? Or not?
- Other types of illustrations needed?
- Could you see yourself reading about 20 more chapters written in the same style and with the same type of content? (From Nodes API to HyperlinkProvider, from Refactoring API to Lookup?)
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:
Updated: pilot-chapter-registering-a-framework.pdf
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!
Sep 08 2006, 07:30:01 AM PDT Permalink
19 Comments
Trackback URL: http://blogs.sun.com/geertjan/entry/pilot_chapter_for_upcoming_netbeans
Comments:
Hi,
Here's a short feedback :) :
Is it interesting?
Yes it is :). Such a book is really missing, as for many problems is a better approach not to complicate the framework to be more productive, but to build tools that increase the productivity. This way the framework can remain simple an reliable. Such an example is Click Framework - one of the few frameworks that one can master only after one or two days of study.
Is it readable?
Yes.
Is the style conversational? If yes, is that good? If no, how should it be different?
For me, the style is pleasant and I would like if more books would have such a style.
Is it practical? (Could you see yourself picking it up and doing something with it?)
Yes, for sure :). I'm very excited to put in practice what's in there.
Is it the right level of detail?
IMHO it is.
Is it too simplistic? Should it be pitched at some 'higher level'? (And define what that is.)
No, I don't think that it's too simplisting, (as long as it is on a concrete example).
Does it cover everything needed in this area? (If not, what's left out?)
That's very hard to answer. I think only advanced NB architects can answer if all topics are covered (that are supposed to be the responsibility of the WebFrameworkProvider).
Enough screenshots? More needed?
Yep, need more and consistent (on the same theme), and also just like you did: "screenshot regions".
Too much code?
Not if:
Like the tip lightbulb? Or not?
It's OK, but any sign would do it. Highlighting elements in a book is however important. There might be more types of higlight: "tips", "wrong practic", "danger", "short story to exemplify", etc.
Other types of illustrations needed?
Yes. Diagrams to explain things and relations, architecture, workflow, etc. For this chapter there's no need for many diagrams, but for other aspects of the API it would be very important.
Could you see yourself reading about 20 more chapters written in the same style and with the same type of content? (From Nodes API to HyperlinkProvider, from Refactoring API to Lookup?)
I would be very glad to read such a book (if there were one). At the moment is a very hard work (marked with many trial an fail steps) to get things done. Such a book would be the "bible" :).
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?
Both. The user would make the examles to get confortable with the API and to understand and learn what's in there, and than it would put in practice for his own framework.
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)?
Yes. Consistency is very very important, and make things much simpler to understand (and needs no translation process from the reader's side). Aspects that simply do not exsist (or not required) by that "selected" framework should be exemplified on the "official/standard" ones (e.g. Struts or JSF). What framework should be the "selected one"? IMHO it should be one that all people can learn(or need to learn) and is also OK from a SUN perspective and strategy. This could be even Struts if is simpler this way to write a book. As a selfish developer I could propose to use Click, but I don't know what's the SUN policy regarding so small frameworks, so I'm very happy with ANY framework as long as the book helps me create a plug-in for my framework.
Or does the current situation, where a variety of frameworks are discussed, appeal more to you?
No. You can mention the other frameworks too (that they need the one or the other feature more), but IMHO the examples should be consistent and always on the same framework as long this is possible.
I hope the above feedback helps :).
Ahmed.
P.S. an online questionaire would have been simpler and IMHO much more people would have participated :).
Here's a short feedback :) :
Is it interesting?
Yes it is :). Such a book is really missing, as for many problems is a better approach not to complicate the framework to be more productive, but to build tools that increase the productivity. This way the framework can remain simple an reliable. Such an example is Click Framework - one of the few frameworks that one can master only after one or two days of study.
Is it readable?
Yes.
Is the style conversational? If yes, is that good? If no, how should it be different?
For me, the style is pleasant and I would like if more books would have such a style.
Is it practical? (Could you see yourself picking it up and doing something with it?)
Yes, for sure :). I'm very excited to put in practice what's in there.
Is it the right level of detail?
IMHO it is.
Is it too simplistic? Should it be pitched at some 'higher level'? (And define what that is.)
No, I don't think that it's too simplisting, (as long as it is on a concrete example).
Does it cover everything needed in this area? (If not, what's left out?)
That's very hard to answer. I think only advanced NB architects can answer if all topics are covered (that are supposed to be the responsibility of the WebFrameworkProvider).
Enough screenshots? More needed?
Yep, need more and consistent (on the same theme), and also just like you did: "screenshot regions".
Too much code?
Not if:
- It's splitted into fragments - so no big blocks that are larger than a page
- It has your comments, not the brute comments from the original code
- The comments are as text, not as "java code comments" (so that the code looks simpler)
- You explain the point, and let obvious things out (and just a link the the file) - the book is not a reprint of some sources, right? :)
Like the tip lightbulb? Or not?
It's OK, but any sign would do it. Highlighting elements in a book is however important. There might be more types of higlight: "tips", "wrong practic", "danger", "short story to exemplify", etc.
Other types of illustrations needed?
Yes. Diagrams to explain things and relations, architecture, workflow, etc. For this chapter there's no need for many diagrams, but for other aspects of the API it would be very important.
Could you see yourself reading about 20 more chapters written in the same style and with the same type of content? (From Nodes API to HyperlinkProvider, from Refactoring API to Lookup?)
I would be very glad to read such a book (if there were one). At the moment is a very hard work (marked with many trial an fail steps) to get things done. Such a book would be the "bible" :).
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?
Both. The user would make the examles to get confortable with the API and to understand and learn what's in there, and than it would put in practice for his own framework.
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)?
Yes. Consistency is very very important, and make things much simpler to understand (and needs no translation process from the reader's side). Aspects that simply do not exsist (or not required) by that "selected" framework should be exemplified on the "official/standard" ones (e.g. Struts or JSF). What framework should be the "selected one"? IMHO it should be one that all people can learn(or need to learn) and is also OK from a SUN perspective and strategy. This could be even Struts if is simpler this way to write a book. As a selfish developer I could propose to use Click, but I don't know what's the SUN policy regarding so small frameworks, so I'm very happy with ANY framework as long as the book helps me create a plug-in for my framework.
Or does the current situation, where a variety of frameworks are discussed, appeal more to you?
No. You can mention the other frameworks too (that they need the one or the other feature more), but IMHO the examples should be consistent and always on the same framework as long this is possible.
I hope the above feedback helps :).
Ahmed.
P.S. an online questionaire would have been simpler and IMHO much more people would have participated :).
Posted by Ahmed Mohombe on September 08, 2006 at 08:41 AM PDT #
BTW questionnaire:
If you can't use (or SUN/NB don't have) an online questionnaire, you can use Form Assembly, cause it's free for the amounth of information you need, and you can setup such a form in a few minutes. This would be for the users much simpler to give you feedback.
Ahmed.
If you can't use (or SUN/NB don't have) an online questionnaire, you can use Form Assembly, cause it's free for the amounth of information you need, and you can setup such a form in a few minutes. This would be for the users much simpler to give you feedback.
Ahmed.
Posted by Ahmed Mohombe on September 08, 2006 at 09:04 AM PDT #
I love it, definitely a few more screenshots would be helpful. I will actually be using it this week to add support for a web framework.
BTW, can update the pilot chapter's "Alternate Approaches to Attaching a Framework's JAR Files"? I am actually really interested in that part.
I would buy the entire book in a second.
Posted by Jacek on September 08, 2006 at 10:00 AM PDT #
Such a book is sorely needed. I use netbeans for my home projects, but use eclipse at work (the day job is inflexible about tool choices). the Eclipse developers guide is a big help, albeit a bit flawed. i generally prefer netbeans, but find the lack of a resource similar to the Eclipse book to be a hindrance.
Posted by Richard Welty on September 08, 2006 at 03:47 PM PDT #
Thanks all for the comments! I have updated the link, the document now includes some additional info, including what Jacek asked for above. The more feedback from anyone on the details (especially from people actually already using the chapter to integrate a framework), the better!
Posted by Geertjan on September 08, 2006 at 06:07 PM PDT #
I think more than showing what all can be done with the APIs ..it is more imp for any module/platform developer to understand the significance of using a particular api ..the situtaions when to use that api, and when to use the normal swing apis since netbeans is so huge and is a very steep learning curve for swing developers.
Posted by pavan kumar on September 08, 2006 at 08:38 PM PDT #
What can I say. Finally !!! The last book that talk about module development is written agains 3.6 and 3.6 releases and NetBeans has gone a long way since then. I also think that this book should only describe the latest APIs (Lookup and not all the framework that lead to Lookups, ...). There should be tons of examples.
I hope the book will not be just javadoc in paper form, since many developers have trouble reading the javadoc.
I'm also affraid that by the time the book will come out the APIs will be on a much higher level. the same happened when the last book came out. It was written against 3.5 and 3.6 and the release was 4.0.
If you can solve these problems the book will be a bestseller. :)
Consider me a buyer !! :))
Posted by Kovica on September 09, 2006 at 02:59 AM PDT #
Perhaps a quick reference in the back on the APIs as a supplement would be really helpful, not at the javadoc level but perhaps supplemented with examples showing the intended usage.
I'd also like to see some explanations of how the APIs layer over the basic IDE, e.g. what is the relationship of a library wrapper to the way the IDE handles things in the absence of a library wrapper.
Posted by Richard Welty on September 09, 2006 at 06:26 AM PDT #
Hi Pavan. Sure, that will also be discussed in the book. But, at some point, the book should talk about what can be done with the API, I think... :-) Kovica and Richard Welty, thanks for your thoughts too. Keep them coming, by the way.
Posted by Geertjan on September 09, 2006 at 06:31 AM PDT #
Geertjan,
first, the answers to your questions:
Although knowing the layer.xml is listed as a prerequisite, I've always found that difficult to understand the "why" of certain things in it. For example, why do the java templates always need to have a .template extension ? Along the same lines, it would probably be helpful on adding some info on why certain things are done in a certain way - maybe that could be another type of lightbulb that would explain the NetBeans architectural considerations for doing things in certain things. I hope this helps
- Is it interesting? Yes. I devoured it immediately.
- Is it readable? Yes, it was readable for me; however, I can't vouch for everyone as I've spent some time trying to figure out the exact same things that are in the chapter, so reading it was pretty much validating what I had already found out (for the most part). I would imagine though that for a total newbie it might be a bit overwhelming in the amount of information that is found in it.
- Is the style conversational? If yes, is that good? If no, how should it be different? The style is OK, I really didn't pick up anything negative about it.
- Is it practical? (Could you see yourself picking it up and doing something with it?) Most definitely. You are always ahead of my by a couple of steps with things : I wish I had this when I was trying to figure out the exact same things (e.g. registering the framework provider stumbled me pretty badly).
- Is it the right level of detail? It h has maybe a little too much detail, although that's not necessarily bad. For example, where you explain how to create all the necessary files for the framework, even before, I always thought that there would have to be some more polished way of doing it (e.g. too much implementation detail seems to be in it). On the other side though, it probably would be helpful to have more detailed explanations of what each couple of lines of code do (e.g. Manning books are a good example of that) - for example, the example in 4.2 only explains 2 of the lines and the rest of it is not explained.
- Is it too simplistic? Should it be pitched at some 'higher level'? (And define what that is.)
- Does it cover everything needed in this area? (If not, what's left out?) I have been considering using some of the stuff that Xzajo does here(e.g. velocity templates) for the code generation. It probably would be helpful to show the usage of a more "standard" tool for code generation.
- Enough screenshots? More needed? More screenshots are always nice to have. They don't necessarily have to show each action performed, but for example it would have been nice to see the project structure (e.g. all nodes expanded)
- Too much code? Not necessarily too much, but more comments, especially in the examples section would be nice.
- Like the tip lightbulb? Or not? The light bulb is really nice.
- Other types of illustrations needed? This seems like a good start.
- Could you see yourself reading about 20 more chapters written in the same style and with the same type of content? (From Nodes API to HyperlinkProvider, from Refactoring API to Lookup?) It probably wouldn't be possible to read the whole thing in one sitting (e.g. as the content is very practical). For some reason (could just be my pdf reader - kpdf), but the font seems very dry and boring. For example, I found it difficult to read the whole introduction as the text seems to be too crammed. It would probably be nice if it would be possible to have the project in each chapter fairly self contained, so that if a user is interested in only particular aspects of building the module, he/she wouldn't have to read all the previous chapters. At the same time, it would probably be nice to have a running case study across the whole book that would maybe illustrate "the building of a framework support module in NetBeans".
Although knowing the layer.xml is listed as a prerequisite, I've always found that difficult to understand the "why" of certain things in it. For example, why do the java templates always need to have a .template extension ? Along the same lines, it would probably be helpful on adding some info on why certain things are done in a certain way - maybe that could be another type of lightbulb that would explain the NetBeans architectural considerations for doing things in certain things. I hope this helps
Posted by Alex Kotchnev on September 09, 2006 at 06:19 PM PDT #
This is possibly a bit tangential, but may have some relevance. I've been developing in swing for 5 or so years, and have only within the past few months started working in eclipse plugins at the day job and trying to develop a netbeans platform application at home (http://scale-app.sourceforge.net/ if anyone cares). what would be really useful on the netbeans side would be something at the level of "so you know swing, this is how you do standard swing things in the API". i've been considering offering to help with such a document, subject to the constraint that i'm still learning how to do swing things in a netbeans platformesque way.
Posted by Richard Welty on September 10, 2006 at 08:04 AM PDT #
Alex, brilliant comments -- especially because you're someone actually using this type of functionality in your own module. All your comments will be taken very seriously, thank you immensely. Hope to check back with you sometime when the chapter and the rest of the book is more solid.
Richard, good idea -- in fact, that's something I've been confronted with in the Visual Library API (discussed in some detail over a few blogs from recently). One comes to an API from a Swing background and then has to rethink GUI programming to some extent and end up with similar components to those provided by Swing. Some kind of table that draws comparisons and differences would definitely be useful, especially in the platform part of this book.
Posted by Geertjan on September 10, 2006 at 09:55 AM PDT #
@Richard
I like the "NetBeans for Swing developers" suggestion, although it's basically a chapter topic suggestion, rather than a comment regarding the pilot chapter.
@Alex
I agree with the font comment. I'd go so far as to say a serif font might be a better choice, even though it's been years since I read anything more than a brochure on printed paper rather than on-screen.
@Geertjan
I'm sorry to say I'm short on time to read the whole chapter right now (as much as I'd like to), but I've skimmed over the contents and it feels like I'm reading a chapter from a reliable, step by step reference manual. This is good. The thing is, a book about netbeans platform development (that's how I see it, even if you call it "...for plugin development") written along the lines proposed by the pilot chapter would have dozens of chapters...maybe as much as 30. "JNLP", "update center", "NB and Nodes", "Wizards", "Help system integration", "Options", "Branding", "user access rights management", "Spring/other framework integration"...just to name a few, and I'm far from what you'd call an "experienced NB developer", so there certainly exist many more topics.
Posted by Tomislav Nakic-Alfirevic on September 10, 2006 at 10:18 AM PDT #
Tomislav (Tommy?) -- Agreed: About 30 chapters would be needed. However, it is unclear whether we'll be able to do that within the timeframe and might have to limit ourselves. However, there's always another book and -- because we're aware that having books on something makes the something more generally accessible -- we really see this as the first of SEVERAL books. So, that's how you should see it. It's a big change in mindset, because up until now we've 'only' had the Definitive Guide in the module development area. Now we're (at least thinking of, nothing 100% definite) having more as time goes by. So, what isn't covered in this book, will be covered in another book.
Posted by Geertjan on September 10, 2006 at 10:22 AM PDT #
If the group decides to work on Module Development exclusively, please at least create some web-only content for platform.netbeans.org that covers the areas that would have otherwise been in the book had it covered Platform-specific development.
Posted by John on October 04, 2006 at 11:17 AM PDT #
John, the only area that is specific to application development (as opposed to module development) is the area of 'branding', and there should be something about that in the book.
Posted by Geertjan on October 22, 2006 at 12:41 AM PDT #
I went to recive documents about NetBeans 5
Think you
Posted by Lassaad melliti on December 27, 2006 at 03:33 AM PST #
Any update on the status of this book?
Posted by hilz on January 07, 2007 at 01:44 PM PST #
On the 15th of this month there should be an exciting update... so mark your calendar!
Posted by Geertjan on January 07, 2007 at 01:46 PM PST #
Post a Comment: