Index

[Tony Weddle]

Has anyone else had problems with the index of this book? I've only had it for a few days, so it's a bit premature to pass judgement, but I've rarely been able to find what I'm looking for there. This problem that I had about the refreshing the project is an example. I know that there is an API for IResource somewhere in the book, as I came across it yesterday, but there is nothing in the index that leads me to it and nothing that leads me to how to get the project resource, from a plug-in. I had a similar problem when looking for information on selected objects and pop-up menus; there is nothing in the index for ISelection or pop-up menus, and very little about selected resources. More recently, I've leaped ahead a few chapters and seen references to RFWS considerations. The index doesn't even have it listed, so I had to trawl through looking for the first reference, to find out what RFWS is all about.

It looks like it's going to be a good book, but the index, so far, is ... well ... less than helpful.

In these situations, an electronic version, would be useful, in that I could search for information instead of trying to use the index.

[Eric Clayberg]

The problem with indexes is that they can never be big enough or inclusive enough to include everything you might want. In fact, most indexes are only as good as the last thing you couldn't find (which is to say that most indexes are not very highly rated). It's sort of like domestic and international security...the FBI/CIA/Whatever can foil terrorist plots all day long, but they are only as good as the last attack they did not prevent.

The index contains a great deal of material, but it does not list every Eclipse API or every API used anywhere in the book. It also does not include every combination of cross-indexes that might make sense. The RFWS material is in the index, but it is generally found as a sub-item of some other category (like Views or Wizards),

When Dan and I originally indexed the book, we included every API that was referenced and multiple cross-index entries for almost every topic. Our index ended up being about 50 pages and was considered overkill by the publisher. They opted to bring in a "professional" indexer who produced the current index (25 pages) without any input from us (we didn't even get to see it until the book was already at the printer). That said, I think the current index is pretty good relative to indexes in similar books or other books in this series. It does have some important omissions which we are trying to compile for a future revision. If you come up with some specific entries that you feel should be added to the index, let us know, and we will add them to the errata section of the book web site.

[Tony Weddle]

Thanks, Eric. I know indexes can be difficult, to say the least, as I've worked with technical writers in the past.

It may just be the mode I'm in at the moment; trying to change an existing plug-in, with almost no knowledge about how to develop plug-ins. Therefore, I'm constantly looking in the index trying to find information. I have to say that, so far, most of the information I've looked for, I haven't been able to find through the index. The contents also doesn't go to the depth of many books (I'm thinking of the kind of programming books that have a "contents at a glance" and an in depth contents for each chapter). Consequently, using the book as a reference is very difficult. This may not be its intended use, of course, so any criticism of the index and contents may be harsh.

Another example: I'm now looking at fixing the Ant script for the plug-in I've been working on. So I checked in the index under "build" or "building". There seems to be nothing there about building the plug-in, though looking at the BUILDFILE reference would get me to the right general area. On the other hand, if I'd thought to look under "Ant", instead, I'd have found plenty of references. Some link to the Ant references, from "build" would have been nice.

[Eric Clayberg]

While I can appreciate your frustration with the index (and agree to a certain extent), some of your frustration here is misplaced. In general, the book is a good reference for building Eclipse plugins, but it does make one or two crucial assumptions, if you are going to use it in that manner. If you are going to use it as an ad-hoc reference, you need to have either a) read the book or b) be somewhat familiar with Eclipse plugin development and terminology. If you are unfamiliar with the basic terminology (e.g., your earlier comment about not knowing what an "action" is), then you won't have a good basis for finding anything in the index.

For example, had you known that the general term for the thing you wanted to filer was "action", then looking in the index under "Actions" would have lead you to "filtering and enablement" right away. Likewise, your comment about "RFWS". There are lots of index entries dealing with RFWS - either under the appropriate topic area (like "Views") or gathered together under "Ready for WebSphere Studio (RFWS)". Granted, there should be a specific "RFWS - See Ready for WebSphere Studio" entry in the index, but the "RFWS" term is introduced right up front in the book's Preface. At minimum, you should probably read the Preface and Chapters 2 & 3 just so that you can ground yourself in the basics before trying to hunt through the index.

This book is also not an "Encyclopedia of Eclipse Plugin Development" that covers all possible topics (we would need a couple more volumes for that). It is primarily a generic book on plugin development rather than a specific guide on building specific types of plugins. We don't, for example, go into detail on using the GEF, EMF or JDT libraries as those could easily expand into books all by themselves (and in the case of EMF, it did). Thus, this book deals primarily with generic IResources and IProjects rather than the specifics of the JDT and IJavaProjects.

[Tony Weddle]

Eric,

I agree with almost everything you say. Just a note on the preface, though: I did read some of the preface but not all of it. I tend to think that if information is important, then it should be in the main body of the book. Any text before the book proper (chapter 1) is almost meta-data (how the book is organised, textual conventions, intended audience, contact information, and so on). Yes, RFWS was mentioned in the preface but I didn't get that far - after two Forewards and half a preface, I just wanted to get into plug-ins. Its first mention in the book wasn't expanded on, until later.

But you do say, in the preface, that the book can be used as a reference for experienced plug-in developers. So I fully accept what you say and shouldn't have tried to use it that way, as an inexperienced plug-in developer. But I would have loved to have seen your 50 page index! And an extended table of contents.

It's turning into a very good book, by the way.