The Artima Developer Community
Articles | Discuss | Print | Email | First Page | Previous | Next
This article is sponsored by Business Objects.

Using a Decision Tree to Navigate Complex APIs
by Colin Gray
May 26, 2005

Page 1 of 2  >>

Advertisement

Summary
As software products become more complex, developers must invest increasing amounts of time to learn about new API and product capabilities. Traditional documentation tools were not designed to help navigate that increasingly complex landscape. This article reports on an interactive documentation navigator developed by Business Objects, S.A., for their Crystal Reports and enterprise reporting-related products. That documentation tool not only presents API components and describes how to use classes and methods of an API, but also guides a developer through the decisions of what API elements to use to accomplish a given task.

In his autobiographical travelogue Wind, Sand and Stars [see Resources], Antoine de Saint-Exupéry sums up the beauty of airplane design: "In design, you have reached perfection not when there is nothing more to add, but when there is nothing left to take away." An aviation pioneer and globetrotter long before the jet age, he extols us that "He who would travel happily, travels light."

As developers, we can easily feel with Saint-Exupéry: While he had to find his way in the complexity of a cockpit, our job is to navigate around increasingly complex APIs to get our job done. We would all rather travel light, but we also must deploy complex software solutions to help our organizations stay competitive. Those solutions, in turn, require that we make use of components and APIs that present increasingly more features. With more features, we have more packages, classes, methods, and configuration options to keep up with.

Increased complexity confronts us not only during development time, but also in the process of evaluating new APIs and software products. It used to be that we could simply download a single package from a vendor's Web site, install it, fire up some examples, have a look at the APIs—and pretty much be done with the evaluation even before our cup of coffee grows cold.

That is no longer the case. Just a cursory look at the latest J2SE, J2EE, or .NET platform APIs can put us at unease. Evaluating such products and APIs might take days or even weeks of trying out different features and examining different API subsets. That evaluation requires increasingly significant investment from both potential users and software vendors, be they commercial outfits or open-source projects. The voluminous documentation of open-source projects, such as Hibernate, Apache Jakarta, or NetBeans illustrates that taming the complexity beast is no privilege reserved for for-profit software vendors.

One solution to the problem of evaluating and learning about increasingly complex APIs comes—not surprisingly—in the form of software. While traditional documentation tools are still lagging in helping to cope with complexity, a few efforts under way aim to produce the kinds of interactive documentation that can ease someone into an APIs complex innards. This article provides a brief review of a few approaches, including an interactive web application that uses a decision tree to help users navigate complex APIs.

Taming complexity in Java APIs

A very simple example of such an effort provides a graphical overview of the hugely complex J2SE API. While it's easy to mistake it for cute marketing graphics, the J2SE Platform Overview is actually an image map that gives a birds-eye view of different parts of the J2SE 1.5 API [see Resources]. Clicking on any area of this image takes you to a Web page for the appropriate API. Each of those API areas provides a brief overview, and then gives URLs to the relevant Javadoc documentation. While simple, the image map-based documentation overview helps a developer understand what's available in a complex API bundle.

Still, just knowing what's available does not immediately help a developer understand how to use an API's classes and methods. Explaining that detail has traditionally been the task of a documentation tool, such as JavaDoc [see Resources]. While JavaDoc has evolved over the years, it's basic paradigm of generating documentation from source code hasn't changed. With an API as large as the JDK 1.5 APIs, simply presenting classes and methods in an HTML page becomes limiting: There are just too many classes and methods. It's similar to the classic problem of not being able to see the forest for the trees. Although you can see individual trees clearly, by reading the documentation of individual classes, there are so many of them that it is difficult to get the big picture.

The sheer number of HTML pages that make up the J2SE 1.5 JavaDoc presents the same problem search engines try to solve. An obvious next step for JavaDoc would be to provide a search capability. That capability is already a part of JavaHelp, and it might serve developers as well as it serves an application's end-users, JavaHelp's typical audience [see Resources].

A few open source projects are already addressing this need, such as the very simple JavaDoc- Search tool hosted on SourceForge [see Resources]. A more interesting project is run by the JavaLobby folks at jdocs.com [see Resources]. They have compiled a list of so far 132 Java APIs, and provide textual searching across those JavaDoc files. In addition, they also provide a way for developers to post and read comments about those APIs.

While the Jdocs site brings us one step closer to showing how to use certain APIs, it still does not help us decide what API elements to use to solve a given problem. That guidance is traditionally reserved for API tutorials that do not normally form part of a traditional API documentation set. Moreover, tutorials are by very nature selective in what aspects of an API they cover.

Another approach to guiding a developer through a complex API was recently implemented by Business Objects, S.A., the maker of Crystal Reports. Business Objects has seen its product offerings, which include APIs, grow in number and complexity over the years. To help developers decide which of its API elements to use to solve a given problem, Business Objects recently created an interactive object model decision tree web application [see Resources]. This application guides developers through Business Object's APIs using DHTML and JavaScript, and is available on Business Objects' Developer Zone website.

Page 1 of 2  >>

Articles | Discuss | Print | Email | First Page | Previous | Next

This article is sponsored by Business Objects.

Sponsored Links



Google
  Web Artima.com   
Copyright © 1996-2014 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us