"Hello, World," for example, is standard - but is too simple to illustrate anything more complex than compilation and linking, if the language in question has a linkage phase (other than at runtime as Java does). Complex APIs, such as J2EE has, generate tutorials that are stunning in complexity. Even Spring, with a fairly simple API and a goal of simplifying J2EE, has a rather daunting manual, yielding attempts to write introductions "for dummies."
The FSF's "Hello, world" checks mail (among other things!), on systems where such facilities are available, but using that for a tutorial tends to be counterproductive - as mailchecking in Java is too flexible for a "hello, world" scenario, involving installation and understanding of the Java Activation Framework (JAF), comprehension of how MIME messages are composed (because JavaMail represents the MIME object model instead of just "allowing things to work"), and an understanding of object-oriented principles - far beyond the scope of "Hello world, plus a little."
However, there are three things that can typically be blamed for the lack of effectiveness of a given tutorial: the tutorial's scope, the APIs being covered are flawed, or the APIs' level of abstraction.
- If it's the tutorial's scope, then the tutorial might be too limited. ("Just 'Hello, world?'") Likewise, many tutorials have to explain basic concepts to readers who may not be ready for the core (or "interesting") points of the tutorial, which has the effect of turning away the people most likely to benefit from the tutorial.
- If it's not the scope, then possibly the API in question is just too complex, as one experienced Java programmer suggested when faced with sending multipart email through JavaMail, which was the basis for this question. One could blame the EJB specification of this, during much of its lifecycle, for example, or the aforementioned JAF.
- The APIs' level of abstraction might also be the problem. For example, Apache SOAP was originally written at the "wire level" where one built messages largely at the "SOAP protocol" level, much as one does for Apache XML-RPC today, but Axis and most other successful SOAP libraries allows developers to focus on RPC. To use a JavaMail example, perhaps tutorials shouldn't focus on JavaMail, but on APIs that might use JavaMail underneath, such as Jcake or other such packages, because JavaMail focuses on the protocol and not the purpose of actually sending mail.
So what's the answer? Are Java APIs too complex to write decent tutorials for? What do TSS readers think is the sweet spot for writing introductory or teaching material for Java APIs? What tutorials do you think are well-done enough to serve as models for others?
(For the record, tutorials are accepted by TSS for publication, if you're wondering - although Your Humble Editors would hope that 'Hello World' for complex APIs such as portlets would be avoided in the future.)