DocumentDeclarativeAPI

From APIDesign

Current revision

Declarative Programming offers us higher level abstractions. Such abstractions usually allow API users to specify what shall be done without the need to describe how to do it. Nice difference between these two approaches can be seen when packaging an application in Maven or in Ant (the build.xml and pom.xml are APITypes). While in Ant I would need to copy all the library JARs into appropriate location and then generate main module manifest Class-Path attribute manually and ZIP the whole bundle, in Maven I can just choose the right plugin, tell it that my libraries shall are in lib directory and that I want Class-Path attribute and the rest is done automatically. This is perfect, but it has its own hidden issues.

It seems to me that the documentation for declarative APIs cannot be the same as for procedural ones. The higher level abstractions may be too abstract for consumption by regular API novice. As shown in my Maven adventures, I had a vision of what I wanted to do, but I could not select the appropriate abstractions (e.g. the Maven plugin) to help me in achieving my goal.

In case of procedural Ant, this is much easier. I know that I need to copy library JARs. Guess what is the appropriate tool? Yes, it is the copy task. I need to create a ZIP file. Guess what one shall use? Of course, the zip task. Finding the right mapping is easy, as Ant is naturally mapping the (simple) concepts user has in his head to the right tools. Of course, only simple concepts are mapped. As soon as one starts to think about generating the Class-Path attribute, one will get lost. This is just too complicated to be automated in Ant (as far as I am aware one of the right tools is pathconvert task, but the whole order of steps is quite complex).

Getting High

The trouble with high level concepts is that there needs to be some entry point that maps the actual API user need to the right tool. Treating the Maven plugins as such entry points is not sufficient. Every plugin has huge set of additional configuration options and can be tweaked to do almost everything. So when looking at assembly plugin documentation I have seen that this is useful for creation of uber JAR and I immediately have lost my interest. If I investigated it more, I would have found out it is useful for solving many other goals as well. But API shall be easy to use.

The entry point for an API should be a usecase. A description of an (expected) user need. This is true for any API, but clearly for Declarative Programming this is more important than ever. In this case the usecase is to package ZIP file with multiple JAR files. This would immediately trigger my (or google's, when I was querying for keywords like ZIP maven JAR Class-Path) attention and I could then follow up to the actual example describing how to realize my usecase via pom.xml configuration.

Abstractions Need Usecases

The more abstract concept you expose, the more important good usecase is. For example NetBeans is using Lookup concept, which is quite abstract and used for various, at first sight unrelated, goals. It is almost impossible to explain newcomers the Lookup API itself. It always needs to be introduced by real problem, real usecase. For example: if you want to MVC in NetBeans, you need Lookup. Use it this way!. Then the usecase is clear, and the actual (originally confusing) API is just a tool to realize that usecase.

Abstractions are soul of API design. They create the high level concepts that simplify our life (when one knows how to use it, the Maven is really more friendly than Ant). Yet, abstractions are not the primary goal. Humans need a guide to use the abstractions. Human need good usecases that document declarative APIs.

What Do API Users Say?

Too many developers are focused on the mechanics of how a task will be performed and the steps required to perform them. Typical documentation of software explains what command line switches are available, but not why you might want to use them. I have been frustrated by this for years. I always skip to the "Examples" section of any doc, as I usually can infer use cases from the examples far better than from studying method signatures in the abstract. A classic example would be the Java API docs. Why would I want to use a LinkedHashMap? Maybe I slept through that lecture in CS class. It would be neat to make a pivoted set of docs for the JDK in terms of patterns, like LRU Cache => LinkedHashMap. The only way I've learned Maven is to study other people's POMs, guess-and-check, and then discuss.

-- Basscakes 15:55, Sep 15, 2009