Tutorials are hard to write. If you make them too short, they tend not to convey the information people need; if you make them too long, people lose patience and stop reading them. Likewise, examples need to be real-world, but real-world examples tend to be too complex to communicate in a tutorial.

"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.)

Unfortunately, there is no "one size fits all". The target audience needs to be defined. If your target audience is developers that have no experience whatsoever on the topic of the tutorial, then a "Hello World" type example would be beneficial. This will help the target audience get a head start on the technologies discussed.

If your target audience already has some experience on the topic, then specific, more advanced topics can be discussed.

I think the best way to appeal to a wider audience is to split the tutorial in parts. Starting with a "Hello World" example to get started, then moving on to more advanced topics. Readers familiar with the technology can skip the "Hello World" part.

Hi,

Well, there can not be a definitive way to answer this and it also depends the initial knowledge/idea/concept behind the technology of the person who will be using the tutorial.

I think, a tutorial should essentially have all the topics explained slightly in detail (not too much), detailed enough that the person gets the hang of the main purpose behind that feature, alongwith an example which shows how you would really do when you are working on a real world application. For example, if we are talking about writting MDBs in a J2EE application, after explaining what an MDB is, how is it used in an application and what all is need to implement like the important classes, some standard (non Application Server specific, though writting about how some mainly used App Server need some information in generic way could be very helpful here) configurations like setting up the messaging sever, etc., and an example of how other application uses this MDB in its code could be very helpful sometimes.

Gauzy

This comment applies to both books and tutorials...

Effective tutorials generally have a very narrow scope in terms of the features that they introduce, but to make the features relevant, they should be embedded within a "real world" setting.

For many Java APIs, you need to have a functioning application that already makes use of the API. Rather then demonstrating how to build an application from scratch, demonstrate how to modify the application's behavior by utilizing the API.

--John

I think a tutorial should demonstrate a simple but common use case for the API.

For example, a web framework tutorial ought to demonstrate having a simple form, passing data to server side components, "saving" that data (you can cheat on this last part by saving the data in memory only) and displaying a confirmation. It should also demonstrate the other basic framework features (configuration, flow control, error handling, etc.). Personally I like to use login forms (two fields, well known scenario).

A middle-tier framework ought to demonstrate defining and configuring a semi-realistic service (e.g. logging), and making that service available to other frameworks.

Anyhow, something of that nature.

Java API documentation suffers from a major problem, regardless of whether it
came from Sun, Apache, or an independent open-source or private provider: the
API (what to use) and the HOWTO are almost always in separate places. This
results in these problems:

• Information overload - too many open tabs/browser windows
• Style inconsistency
• Trivial examples that aren't applicable
• Old cruft isn't removed/maintained by the authors

The fact that most significant Java APIs build on pre-existing results in
another problem: setting up a new API may involve bringing with it several
other technologies that need to be set up and configured (i.e. for "worst cases"
look at Axis or FOP, with the latter pretty much dead by now). All these things
conspire to make it hard to keep the documentation up-to-date, interesting, easy
to follow, and relevant in the use and combination of features in the API.

One of the best examples of API documentation is the PHP Manual. It lists all the APIs a
single document, and all but the most trivial are documented thoroughly. Users
are invited to provide examples, and most functions, classes, and methods have
rich examples of usage, how to combine a given API call with others, and some
times even examples of other calls that may do a better job than the intended
API. References to external packages (i.e. they have something called PEAR) may
not appear in the main body of the document but users will present them in the
examples.

Following on the example from Joe's original post, let's look at the
documentation needed for sending a multi-part MIME message in Java Mail vs.
PHP:

In Java:

• The Java Mail API and documentation; the documentation is in Acrobat PDF
  format and javadoc
• Don't know JAF? Well, you need that too
• Some kind of J2EE container would be nice; otherwise you need to figure out
  how to write a wrapper in J2SE to activate this
• Need to do multi-part? Go read the RFCs at the IETF site and translate what
  that means in the context of the PDF manual, the API, and what you're trying to
  do

In PHP:

• Read the mail() function documentation and the user comments

Everything you need is there; if you're a casual mail API user, you don't even
need to bother reading the RFC.

Perhaps it is too late for the Java world to adopt this style of documentation
but I believe it'd do a world of good. A blend of the J2SE/J2EE javadoc files
with the Java Tutorial and a wiki would be a most welcome addition to the
toolset.

What do you think?

Cheers,

E

Note that annotated javadocs have been tried by Javalobby and a few others; there've been objections to such efforts, and in all honesty, while I think an annotated central javadoc is a brilliant idea, I think it's something Sun has to do rather than an external body.

That leaves the question up to Sun. Anyone @ Sun care to comment?

Anyone @ Sun care to comment?

No, Sun will not comment. Why should they? They are a research company, and you are now only a simple web site that brings news to developers.

Sun will not comment.

To those in this thread who would change Javadoc, I would ask this question: If you open your daily newspaper, and find that it doesn't contain an in-depth scientific study on the eating habits of migratory birds, would you complain? Would you ask News Corp (or whoever) to change it?

Or isn't that why you get a daily paper?

To those in this thread who would change Javadoc, I would ask this question: If you open your daily newspaper, and find that it doesn't contain an in-depth scientific study on the eating habits of migratory birds, would you complain? Would you ask News Corp (or whoever) to change it?Or isn't that why you get a daily paper?

That's a stupid analogy, but I'll bite. I wouldn't expect that in the San Francisco Chronicle but I'd expect it in the Journal of Ornithology.

When it comes to newspapers, yes, if I want detailed financial news I skip the San Francisco Chronicle in favour of better sources like the Financial Times (allegedly better than WSJ as well). And when they discuss a topic of relevance you can usually find the article, a follow-up op-ed, the Lex section, and supporting materials in data boxes. Check it out one day; it's the "pink" newspaper that clued business people read.

So yes, I would expect the javadoc/Java Tutorial to be merged into a more cohesive document. I believe we'd all win.

Cheers,

E

I would expect the javadoc/Java Tutorial to be merged into a more cohesive document. I believe we`d all win.Cheers,E

Why? When I go to the API to look up the documentation on a method, I just want the technical specs. What's expected in the input and what behavior I can or cannot count on. I don`t want to wade through a tutorial to find this. Tutorials are usually read once, APIs are read over an over again. They are reference documents. The tutorials are not had to find. I don't see the problem.

In any event, as far as I am concerned a tutorial should show you how to get up and running with a new tool without a lot of flailing. From there on out, I just want the documentation to be easy to reference.

When I go to the API to look up the documentation on a method, I just want the technical specs. What's expected in the input and what behavior I can or cannot count on. I don`t want to wade through a tutorial to find this.

I invite you to read the PHP Manual to see how they did it. A reference page describes the API technical specs at the top. The rest of the page shows user-submitted examples of the use of said API in a given context. Look, for example, at the page for LDAP documentation:

• Introduction, requirements, installation
• Predefined constants
• List of functions
• User comments presenting issues that may not be apparent like how to connect to Active Directory (it's dirty)

If you click on any particular function, say ldap_connect, the page will have a similar structure: Description, API, arguments description, etc. followed by user-contributed notes. Notice too the not-so-coincidental resemblance of the format to the javadoc pages when it comes to the API description. Navigation to related functions (i.e. "packages") on the left. And so on.

The point is that both can coexist and make for a better manual; there is no need to keep separate documents in multiple places and formats to elucidate as much information as possible in the shortest amount of time. This is one of the reasons why the PHP Manual is considered one of the best in the web (regardless of how you feel about PHP itself).

Cheers,

E

Note that annotated javadocs have been tried by Javalobby and a few others; there've been objections to such efforts, and in all honesty, while I think an annotated central javadoc is a brilliant idea, I think it's something Sun has to do rather than an external body.That leaves the question up to Sun. Anyone @ Sun care to comment?

I believe it's unfair to ask Sun to own up a site for Java on one site and keep complaining that Java should be made as an open-source, license-free community site on the other.

Since Java has become a community-based software, it should be a part of a community site such as Apache rather than that of Sun.

In anycase, this already has been done. Take a look at
http://www.jdocs.com/

As in any case, the site will only be as good as the participation level.

I wasn't saying that it should be made as an open-source, license-free community site. (If I did: where?)

I think annotated Javadoc is a brilliant idea. But while I think Sun is somewhat justified in saying other sites can NOT do it, I think Sun then SHOULD do it. (Note the lack of "open source" or "license-free" in any of this.)

Likewise, I think the original point stands. I don't think annotated javadoc replaces a tutorial, not for Java... but tutorials for Java currently vary wildly in quality.

Short. If you need to write a long tutorial you are straining to teach someone who doesn't want to do his/her own homework. And you can't learn a subject properly without figuring it out for yourself.

Tutorials are like any other form of communication; they are a two-way street, involving a communicator and an audience. Developing tutorials without a conception of the knowledge level of the audience will fail.

I like the concept of Shu Ha Ri as applied to software development. One of Alistair Cockburn's books brought it to my attention. The idea is that learners are in one of three states:

* Trying to learn the rules. Once they have learned the rules well, they have reached "Shu".
* Seeing the good and bad aspects of each rule. Once they have learned when rules are best applied and when rules are best broken, they have reached "Ha".
* After that, learners eventually become so fluent that they leave the rules behind, thus reaching "Ri". At that point, they realize that there is a higher level of abstraction in their discipline and they try to comprehend that, thus reaching toward "Shu" on a higher plane of understanding.

If a developer is working toward a state of Shu, you cannot communicate them in the Ha or Ri way; they won't understand. Similarly, a Ri practitioner will be bored if you enumerate every step to a goal.

See the following two sources in Ward Cunningham's wiki for more info and links:

http://c2.com/cgi/wiki?ShuHaRi
http://c2.com/cgi/wiki?ThreeLevelsOfAudience

There is nothing wrong with the way tutorials are written. The question really should be How should the tutorials be found and read.

Staying on the original question, my ideal tutorial will have information on target audience, tools needed and prerequisite knowledge needed to benefit from the tutorial.

No writer can write tutorials that are helpful to every one. It is reader's responsibility to find the one that matches his/her requirements and skillset. The reader should know that there are:
Introductory tutorials
Multi part tutorials
Tutorials with source code
Redbook types of tutorials

It shouldn't be too difficult to glance at the tutorial and judge it suitability.

Chintan

Javadocs and tutorials should be separated ,nobody want's to search through all the document just for an api spec.

Tutorials have a target audience, so let's leave it that way, i passed long time ago over this problem, if i need a tutorial for something specific i'm searching for that... there will always be a "hello world" example for everything.

ps: sun's j2ee, and Sofia's tutorials are the worst i have ever seen :))), so don't write them like THAT ;)

Java trails were, in my opinion, fundamentally flawed since they weren't well structured.

I've never had the thime to do this, but I think the tutorials should be split into tiers. Each tier should try to list an explicit set of preconditions to understand the tutorial, with links to where you get the understanding of the preconditions:

tier 0 = the glance over, so people can understand the project in a nutshell. explain what it does (I recommend not using the words "powerful", "lightweight", "high-performance" since those are COMPARATORS, yet people never say what they are comparing them to, like the Hibernate website, tho I do like Hibernate). Provide a short history and/or idea of where it fits into the software ecosystem. I.E. Tomcat is a JSP/servlet container that functions as the reference implementation of J2EE servlets, JSP, and tag libraries.

tier 1 = installation instructions, and use a default installation location to reduce variables in the rest of the tutorial like <install dir>. Then Hello World. Then a basic problem the thing is designed to solve (with code), and compare that to another version of the code somewhere else that demonstrates the value of the software. I think there should be 3-4 separate simple examples of applications of the framework/code/app in order to ignite the imagination of potential users and demonstrate useful features and applications.

tier 2 = more examples and feature explanations. A fully-developed tier 2 tutorial and documentation would have references to sample code in every single api class, if there's a javadoc api, but projects rarely reach that level until substantial maturity and popularity are achieved. MSDN is probably a good example of tier 2 tutorials.

subdomains of software should follow the same pattern. So the java base language tier 0 would have links to other tier 0 subprojects, such as the api sets, J2ME, J2EE, and the like. Each of those subdomains would have a tier 1 "hello world" as well.

This is where wikipedia-type systems are necessary. The tier 0 and 1 tutorials are often built on many domains of knowledge (servlets/JSP rely on java, and Web/HTML/HTTP, JDBC on relational databases, SQL, etc).

I think the key is the tiering, and the interlinking of related tiers together.