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 [[usecase]]s that [[DocumentDeclarativeAPI|document declarative APIs]].

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 [[usecase]]s that [[DocumentDeclarativeAPI|document declarative APIs]].

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]].

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 sole 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 [[usecase]]s that [[DocumentDeclarativeAPI|document declarative APIs]].

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 [[usecase]]s that [[DocumentDeclarativeAPI|document declarative APIs]].

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]].

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 sole 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 [[usecase]]s.

Abstractions are sole 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 [[usecase]]s that [[DocumentDeclarativeAPI|document declarative APIs]].

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]].

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 sole of [[API]] design. They create the high level concepts that simplify our life. Yet, abstractions are not the primary goal. Humans need a guide to use the abstractions. Human need good [[usecase]]s.

Abstractions are sole 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 [[usecase]]s.

==== Abstractions Need [[Usecase]]s ====

==== Abstractions Need [[Usecase]]s ====

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]]''. Then the [[usecase]] is clear, and the actual (originally confusing) [[API]] is just a tool to realize that [[usecase]].

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 sole of [[API]] design. They create the high level concepts that simplify our life. Yet, abstractions are not the primary goal. Humans need a guide to use the abstractions. Human need good [[usecase]]s.

Abstractions are sole of [[API]] design. They create the high level concepts that simplify our life. Yet, abstractions are not the primary goal. Humans need a guide to use the abstractions. Human need good [[usecase]]s.

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 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]] in via ''pom.xml'' configuration.

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 [[Usecase]]s ====

==== Abstractions Need [[Usecase]]s ====

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 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 would query it for keywords like ZIP maven JAR) attention and I could then follow up to the actual example describing how to realize my [[usecase]] in via ''pom.xml'' configuration.

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]] in via ''pom.xml'' configuration.

==== Abstractions Need [[Usecase]]s ====

==== Abstractions Need [[Usecase]]s ====

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 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]]. I description of a (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 would query it for keywords like ZIP maven JAR) attention and I could then follow up to the actual example describing how to realize my [[usecase]] in via ''pom.xml'' configuration.

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 would query it for keywords like ZIP maven JAR) attention and I could then follow up to the actual example describing how to realize my [[usecase]] in via ''pom.xml'' configuration.

==== Abstractions Need [[Usecase]]s ====

==== Abstractions Need [[Usecase]]s ====

In case of ''procedural'' [[Ant]], this is much easier. I know that I need to copy library [[JAR]]s. 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).

In case of ''procedural'' [[Ant]], this is much easier. I know that I need to copy library [[JAR]]s. 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).

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 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.

[[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 [[JAR]]s 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.

[[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 [[JAR]]s 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 Programming|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|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) that can help me in achieving my goal.

It seems to me that the documentation for [[Declarative Programming|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|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 [[JAR]]s. 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 it is naturally mapping the (simple) concepts user has in his had 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 still the whole order of steps is quite complex, btw.).

In case of ''procedural'' [[Ant]], this is much easier. I know that I need to copy library [[JAR]]s. 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).

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.

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]]. I description of a (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 would query it for keywords like ZIP maven JAR) attention and I could then follow up to the actual example describing how to realize my [[usecase]] in via ''pom.xml'' configuration.

The entry point for an [[API]] should be a [[usecase]]. I description of a (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 would query it for keywords like ZIP maven JAR) attention and I could then follow up to the actual example describing how to realize my [[usecase]] in via ''pom.xml'' configuration.