DocumentDeclarativeAPI - Revision history

JaroslavTulach: /* Abstractions Need Usecases */

2009-09-16T06:00:17Z

Abstractions Need Usecases

←Older revision		Revision as of 06:00, 16 September 2009
Line 16:		Line 16:

	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]].
		+
		+
		+	== [[Talk:DocumentDeclarativeAPI\|What Do API Users Say?]] ==
		+
		+	{{:Talk:DocumentDeclarativeAPI}}

198.128.44.35: /* Abstractions Need Usecases */

2009-09-15T17:44:56Z

Abstractions Need Usecases

←Older revision		Revision as of 17:44, 15 September 2009
Line 15:		Line 15:
	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]].

JaroslavTulach: /* Abstractions Need Usecases */

2009-09-15T09:08:09Z

Abstractions Need Usecases

←Older revision		Revision as of 09:08, 15 September 2009
Line 15:		Line 15:
	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]].

JaroslavTulach: /* Abstractions Need Usecases */

2009-09-15T08:36:44Z

Abstractions Need Usecases

←Older revision		Revision as of 08:36, 15 September 2009
Line 15:		Line 15:
	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.

JaroslavTulach: /* Abstractions Need Usecases */

2009-09-15T08:35:35Z

Abstractions Need Usecases

←Older revision		Revision as of 08:35, 15 September 2009
Line 13:		Line 13:
	==== 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.

JaroslavTulach: /* Getting High */

2009-09-15T08:34:26Z

Getting High

←Older revision		Revision as of 08:34, 15 September 2009
Line 9:		Line 9:
	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 ====

JaroslavTulach: /* Getting High */

2009-09-15T08:34:06Z

Getting High

←Older revision		Revision as of 08:34, 15 September 2009
Line 9:		Line 9:
	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 ====

JaroslavTulach: /* Getting High */

2009-09-15T08:32:36Z

Getting High

←Older revision		Revision as of 08:32, 15 September 2009
Line 9:		Line 9:
	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 ====

JaroslavTulach at 08:32, 15 September 2009

2009-09-15T08:32:04Z

←Older revision		Revision as of 08:32, 15 September 2009
Line 4:		Line 4:

	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).
		+
		+	==== 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 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.

JaroslavTulach at 08:31, 15 September 2009

2009-09-15T08:31:26Z

←Older revision		Revision as of 08:31, 15 September 2009
Line 1:		Line 1:
	[[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.