There is a new book about the NetBeans Platform and I am fascinated by it. While writing my Practical API Design book I tried to stress as much as I could that proper API entry point should not be default Javadoc with its list of classes and methods, but a list of usecases. Because newcomers starting to use your API are not interested in hierarchy of your classes - they have a real problem and they want to solve it - looking at flat list of all classes won't help them with that! However, if your API contains good list of usecases, the chances are high, one of them matches user's need and it will be easy to use it as a starting point and modify it slightly to solve the actual need.
The NetBeans Platform for Beginners book has exactly this structure. Each chapter is focused on one of such usecase, describes what problem it helps to solve, and only then the book shows the actual Java code on a cute car related sample. The high-level concepts and their usefulness is described first, the actual usage later. Gory API details (like description of WizardDescriptor class) is left for the last chapter. I love the approach: This is the book that should replace our standard documentation!
I often say that I have become good API designer by making all possible mistakes when designing NetBeans. One of such mistakes was not enough stress on usecase description in our Javadoc. We improved significantly in recently designed APIs, but the description of old ones is really too class hierarchy-oriented. We don't have cycles to fix that, but there is one thing I am going to do: I will put a reference to NetBeans Platform for Beginners into each module Javadoc entry page - because, if you are developing modular desktop application in Java, this book is clearly a must read!
Get your copy at https://leanpub.com/nbp4beginners