Zamples Demonstration

In May 2001 a new tool became available for writing online documentation: JSP Explorer.  In his Aug. 18, 2001 review on IBM developerWorks, Alex Roetter said "JSP Explorer shines as a quick way to create interactive documentation for server side production and sample code, and a fun interface to tweak and try code while you are learning it".  Now at v2.3, and renamed to Zamples, the product is solid, scales well, and sports important features such as a customizable security manager and internationalization.

Zamples reduces support and documentation costs for enterprise software vendors, while increasing the vendors' customer satisfaction.  Enterprise software APIs are only useful to professional services groups and system integrators when there is timely, useful documentation available.  The best documentation includes working code examples, but traditionally this requires installation and configuration - which can be costly and time-consuming.

Zamples is equally valuable to individual programmers who require working code examples in order to learn how an API works.  The current version of Sun's Java Development Kit (JDK 1.4) has 24,874 methods in 30,050 classes, and it undergoes an overhaul approximately every 18 months… and that is merely for the baseline Java programming environment!  Sun has stated that they intend to limit the number of new or modified methods in each JDK release to 35% ... which translates to over 8,000 new or modified methods for JDK 5.0!  You can see why programmers need a quick way of learning how to use the API from working code examples accessible online.

Zamples augments Javadocs by backing it with a database and the ability to store live code examples for every method.  When a user clicks on an example's button, another window opens up, containing explanatory notes and the code example is displayed.  Clicking on the button compiles and runs the code example, and displays the result.  The user can modify the code and see the results.  Zamples runs on any J2EE compliant servlet container and works with code examples in almost any computer language.

Each API deployed by Zamples is searchable and features threaded discussion lists, with multiple topics per method.  In this manner a Knowledge Base and a user community forms around the API.  The Knowledge Base moderator can edit the submissions.  The Knowledge Base can be open to the public or integrated with a corporation's directory of users.

We currently provide several knowledge bases available to the public for free.

Doesn't something like this already exist?

It seems that this concept should already exist - it seems like such an obvious idea!  Sometimes the obvious just doesn't get done if it isn't flashy or technically alluring, and most people have difficulty imagining something that they have never seen.  We are the first to create this type of product, which is a combination of software and online content.  About 30% of the programmers and managers that we have shown Zamples to and discussed the product with have told us that they would find such a tool very valuable for their everyday work.  It is interesting to see the their faces light up when they understand how much of their time is wasted searching for or attempting to create program fragments, and what a timesaver Zamples is.

A Non-Technical Tour of Zamples

This tour demonstrates Zamples's features on a Java API.  Java features an automated documentation generator, called Javadocs, that reads the source code and any comments placed there by the programmers, and produces a structured set of documentation.  This tour will show how Zamples's Knowledge Base works with the Java servlet v2.2 Javadocs.

Zamples's Knowledge Base includes a Javadocs converter that augments the HTML files that make up Javadocs so that sample 'live' program examples can be attached to each of the method descriptions in the javadocs.  This means that people reading the Javadocs can try out sample code pertaining to each of the methods that they are interested in, as well as post live problems for tech support staff to address.  All program examples are 'live', which means that tech support staff will have no difficulty reproducing problems posted by users.

Ready?  Let's start the tour.