Zamples FAQ

1. What is Zamples?
2. Who is Zamples for?
3. How do I use Zamples?
4. How do I use Zamples to document my API?
5. Are there any special considerations for service oriented architectures?
6. What's the smallest and simplest way to get started as a publisher?
7. How well does Zamples scale?
8. Will you create the code examples for us?
9. Can I write an online book using Zamples?
10. Why doesn't my new code example work?
11. How does Zamples, Inc. make money?
12. How does Zamples help outsourced projects?
13. Can I write/embed a Zamples client into a development tool?
14. Can I embed a Zamples 'Try It!' button into a PDF, Word or Flash document?
15. How can I learn more?

1) What is Zamples?

Zamples enables interactive online software documentation that integrates community features with executable live code examples. Read more details here.

2) Who is Zamples for?

Anyone who needs to learn how a programming language or interface works can benefit from using Zamples, including individual programmers, system integrators and IT departments.  Software platform vendors and software tools vendors, and businesses that publish web services APIs can use Zamples to support their developer community with live code examples.

3) How do I use Zamples?

RTM, my friend! ;)   The online help documentation is quite complete, easy to navigate and discusses bite-sized topics.

4) How do I use Zamples to document my API?

Read how to do this in our fine manual.

5) Are there any special considerations for service oriented architectures?

Web services APIs are particularly well suited for Zamples, because code examples should be provided in multiple languages for every service. An interesting approach is to use Javadoc as a document structure, and to place code examples in every language that your organization wishes to support in it.  Alternatively, you can just write a free-form document like this one.

6) What's the smallest and simplest way to get started as a publisher?

Use our servers to host your content on an ASP contract.  We will set you up with your own subdomain (zamples.yourcompany.com) and your developers will never know that we are involved.  When you are ready, you can purchase your own Zamples server and install it in your data center, along with the code examples that you have created to that point.

7) How well does Zamples scale?

The number of simultaneous users depends on the type of sandbox required to support the code examples.  Zamples actually provides several different types of sandboxes, some of which have higher overhead than others.  Each time that a code example runs, the execution environment is initialized to a predetermined state so that the execution results are deterministic.  Code examples that require significant setup will not support as many simultaneous users.  If your code examples are stored in a database, the overhead of retrieving them does impact the overall execution speed slightly, although if your database runs on a dedicated machine this extra overhead is not significant.

Some code examples require quite a bit more processing than others - for example, biotechnology code examples frequently require several CPU seconds amounts of processing for even the simplest examples, and this significantly impacts the number of simultaneous users that can be supported.  At the other extreme, for a "Hello, world" code example written in Java 1.4, we have benchmarked an Intel Pentium 4 running at 2.6 GHz at compiling and executing 35 code examples per second (this corresponds to supporting over 2000 online users at once.)  Your mileage may vary.

We use Tomcat to control the sandboxes.  Normal clustering techniques allow several machines to support greater numbers of online users.

8) Will you create the code examples for us?

Our professional services team will be happy to write live documentation for your organization on a time and materials basis.  Please contact us for a quote.

9) Can I write an online book using Zamples?

Certainly!  You can either purchase Zamples as an online server (ASP contract), or install your own server.  We have special pricing for non-profit organizations.

10) Why doesn't my new code example work?

Possibile reasons include:

• syntax error - the error message will guide you
• missing dependencies - a library may need to be installed in the sandbox
• wrong language selected - the Zamplizer has a pull-down menu which displays all the languages available for that Zamples server.  If you write Perl code, but haven't selected the language, then Zamples will think that it is a Java 1.4 code fragment (the default), and it will fail.
• infinite loop - each code example runs under control of a 'governor', which limits the amount of CPU time and disk space granted to it.  If your code example exceeds those limits, it is terminated.
• security violation - the sandbox doesn't let you perform operations that are considered to be potentially security threats.

11) How does Zamples, Inc. make money?

We sell software licences and ASP contracts.  Our professional services group creates code examples for organizations that do not wish to create code examples themselves.  We also provide training for organizations that would like to maximize their investment in Zamples.

Our online code examples are provided as a public service, to show how our technology works.  We don't make money from them.

12) Can I write/embed a Zamples client into a development tool?

Yes!  Read the documentation on the shiny new Zamples REST Interface.

13) How does Zamples help outsourced projects?

Distributed teams benefit from Zamples' code-centric discussion groups.  Once an API is defined, code examples can be used to specify its behavior.  The team defining the behavior can use code fragments as part of their specification, and the implementation team can run the code examples online as unit tests.  The history of the negotiation between the two groups is automatically categorized and available online.

14) Can I embed a Zamples 'Try It!' button into a PDF, Word or Flash document?

Yes! Zamples works from URLs. POST and GET are treated the same - in fact, a request can be any combination of POST and GET.  That means that Word documents, PDFs and Flash applications can dialog with a Zamples server by providing users with Zamples-enabled buttons.

To try this out, when you have some sample code that you like displayed in the Zamplizer page, click on the HTML button.  The right panel will then display HTML for a 'Try It!' button that can be included into an HTML document. You can view a short video of this here (7MB WMV).

15) How can I learn more?

Contact us by email or at 650-345-1140.