|
Sponsored Links
Resources
Enterprise Java
Research Library
Get Java white papers, product information, case studies and webcasts
|
News
News
News
|
Messages: 18
Messages: 18
Messages: 18
Printer friendly
Printer friendly
Printer friendly
Post reply
Post reply
Post reply
XML
XML
XML
|
 |
TSS Asks: How should tutorials be written?
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.)
|
|
|
Message #184759
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
TSS Asks: How should tutorials be written?
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.
|
|
|
Message #184760
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Frameworks for progressive tutorials
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
|
|
|
Message #184763
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
TSS Asks: How should tutorials be written?
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.
|
|
|
Message #184767
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Java tutorials shortcomings: too many cooks?
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:
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
|
|
|
Message #184770
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
TSS Asks: How should tutorials be written?
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.
|
|
|
Message #184775
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Java tutorials shortcomings: too many cooks?
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?
|
|
|
Message #184782
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Shu Ha Ri
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
|
|
|
Message #184785
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
There is nothing wrong with tutorials
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
|
|
|
Message #184804
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Java tutorials shortcomings: too many cooks?
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.
|
|
|
Message #184806
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Nothing wrong with Javadoc
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?
|
|
|
Message #184807
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
TSS Asks: How should tutorials be written?
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
|
|
|
Message #184808
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Ornithology, financial, and Java specialty publications
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
|
|
|
Message #184821
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Ornithology, financial, and Java specialty publications
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.
|
|
|
Message #184860
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Why have the API + tutorial in one (example)
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
|
|
|
Message #184880
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Java doc with user comments
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.
|
|
|
Message #184881
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Java doc with user comments
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.
|
|
|
Message #184917
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
TSS Asks: How should tutorials be written?
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 ;)
|
|
|
Message #184985
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
tiering + examples
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.
|
|
|
| New content on TheServerSide.comNew content on TheServerSide.comNew content on TheServerSide.com |
|
|
Reza Rahman explores the features of the proposed JSR 299, Contexts and Dependency Injection for Java EE (CDI). When approved, it promises to be a key feature of Java EE 6.
(November 2, Article)
SAML is an XML-based standard for exchanging authentication and authorization data between security domains. The single most important problem that SAML was created to solve is the Web browser Single Sign-On problem. Many organizations are debating whether to stay with version 1.1 or move to 2.0. This article makes observations about both options.
(September 28, Article)
Joe Ottinger takes a look at how people learn, and applies it to the practice of programming. He notes that understanding how people learn is an essential part of working in a programming team.
(September 22, Article)
Stephen Maryka gave us an article about the Asynchronous Web and posed a number of questions that get examined like an approach to delivering Asynchronous Web capabilities through extensions to existing Java EE technologies.
(July 14, Article)
JavaServer Faces Flex goal is to provide users capability in creating standard Flex components, part of flexSDK which is open sourced through MPL license, as normal JSF components. This article by Ji Hoon Kim will provide an overview of creating a simple multilingual JSF page consisting of JSF Flex tags.
(June 29, Article)
In this session Jeff explores the key characteristics of successful SOA projects. He covers some of the patterns, and anti-patterns, tool sets, and strategies that he himself learned the hard way. Last, he provides a strategy and blueprint for achieving a high likelihood of success in your SOA project.
(June 23, Tech Talk)
Ari Zilka, CTO of Terracotta, Inc., talks about the new features in Terracotta 3.1, announced during JavaOne and available now.
(June 15, Tech Talk)
In this Tech Talk, Josh Long explores an integration challenge using Spring Integration and walks through the implementation, employing and expanding on the basic patterns of Enterprise Application Integration to tie together components into a function integration solution, and then demonstrates how Spring Integration helps address the integration requirements.
(June 15, Tech Talk)
In this Tech Talk, David Geary teaches you: The basics of Google Web Toolkit; How to implement Ajax-enabled applications in Java; Internationalization; Hooking into the browser history mechanism; Remote procedure calls.
(June 4, Tech Talk)
Jon Kern discusses the best architecture/technical solutions and ensure that they are repeated by all developers. By tackling the architecture up-front in a serial manner, subsequent parallel development will be much more manageable and predictable.
(May 28, Tech Talk)
This keynote describes the frustrations of modern knowledge workers in their quest to actually get some work done, and solutions for how to guard yourself against all those distractions. Neal Ford talks about environments, coding, acceleration, automation, and avoiding repetition as ways to defeat the misguided attempts to sap your ability to produce good work.
(May 26, Tech Talk)
Gil demonstrates how new, aggressive uses of already abundant compute capacity by common applications offer competitive value for application designers.
(May 21, Tech Talk)
Chris Keene introduces WaveMaker as a new way to automate the ability to generate Hibernate classes in order to more quickly bring OR mapping into an application.
(May 19, Article)
In this session Nati Shalom demonstrates how to take a standard Java EE web application and scale it out or down dynamically without changes to the application code. Seeing as most web applications are over-provisioned to meet infrequent peak loads, this is a dramatic change because it enables growing your application as needed, when needed, without paying for unutilized resources.
(May 19, Tech Talk)
Mastering EJB was one of the original and most influential EJB books in the industry. Mastering EJB III now returns with two new expert co-authors, updated for EJB 2.1 and 30% new chapters including security, integration, best practices, open source, and more.
(Book PDF Download)
The Application Server Matrix is a detailed listing of J2EE vendors and their application server products, with information on latest version numbers, J2EE spec support and licensing, pricing, platform support, and links to product downloads and reviews.
(Application Server Comparison Matrix)
|
|
