[Fiware-wpa] Guidelines section for Architecture Description deliverable available on the Wiki

[Leidig, Torsten]

Hi Juanjo,

I think the definitions given in the "Summary of key concepts" is a good foundation for our work and I recognized that you spent a lot of efforts to make them consistent and well-defined. For the public audience it probably has already sufficient level of precision. For internal purpose there are some questions remaining.

FI-WARE Generic Enabler (GE)

It is said that an implementation of a GE provides a concrete set of APIs and interoperable interfaces. But what does the GE provide? An abstract set of APIs and interfaces or no API/interfaces at all?

FI-WARE GE Open Specification

API stands for Application Programmers Interface, which is synonym to Language Binding to me. Since programmers use different languages the use different APIs according to the programming paradigm, I tend to say that a GE Open Specification does not specify APIs. I rather expect something like an abstract interaction protocol (abstract in the sense that no specific technical protocol and no specific data representation is implied).




From: Juanjo Hierro [mailto:jhierro at tid.es]
Sent: Freitag, 3. Februar 2012 08:24
To: Leidig, Torsten
Cc: fiware-wpl at lists.fi-ware.eu; fiware-wpa at lists.fi-ware.eu
Subject: Re: [Fiware-wpa] Guidelines section for Architecture Description deliverable available on the Wiki

Hi,

  I would never call someone stupid for asking questions :-)    Besides, questions that come from a rigorous analysis of terms and definitions are always good questions because it's quite important that we align on terms and definitions.

  Strictly speaking, we should never use the term "Generic Enabler" or "GE" alone in many of our sentences.   It doesn't mean anything tangible.   What do really exist (i.e., refers to something "tangible") are things like:

 *   "GE specifications" (or "GE Open Specifications")
 *   "a GE implementation" which refers to components in a given product that implement a given GE Open Specification and therefore may claim that they are "compliant with the GE Open Specifications".

  Then, whenever we say, as part of a given Architecture Description (which I believe we should not try to call "Specification") something like:

"The IaaS Service Manager GE invokes the xxx operation exported by an IaaS Resource Manager GE to instruct them to provision the VApp"  (A)
we should indeed say:

"The IaaS Service Manager GE implementation invokes the xxx operation exported by an IaaS Resource Manager GE implementation to instruct them to provision the VApp" (B)


  However, I believe that this would lead us to documents that would be rather "verbose".   On the other hand, using (A) instead of (B) in standard specifications is rather common and many people would understand that you should make the distinction but you don't make it to for the sake of non-verbosity.

  I would go for putting a note somewhere at the beginning of the Architecture Description deliverable, where we may say something as:

In order to avoid a too verbose text, we typically use the term "<name-of-GE> GE" or simply "<name-of-GE>" (e.g., "QueryBroker GE" or "QueryBroker") to refer to "an implementation of the <name-of-GE> GE Open Specifications" (e.g., "an implementation of the QueryBroker GE Open Specifications").  Note that the notion of GE is abstract and what actually refers to tangible things are:

 *   "GE Open Specifications" which contain all information required in order to build components which can work as implementations of GEs.
 *   "a GE Implementation" which refers to components in a given product that implement a given GE Open Specification and therefore may claim that they are "compliant with the GE Open Specifications".
You may refer to the set of terms and definitions provided at:
http://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Overall_FI-WARE_Vision#Summary_of_key_concepts_introduced

  Would you agree ? (if you can produce a better text, I would be happy to take it)

  BTW, I honestly believe we provide an accurate definition of terms at the link referred about (part of the FI-WARE Product Vision.  I tell you that I intend to make an serious effort to be rigorous and provide a set of consistent and well-defined terms, maybe we could add "GE implementation" but that was implicit in the existing ones and should be defined as a "Components in a given Platform Product that implement a given GE Open Specification".

  As for the template ... I'm not sure what do you mean what you say when you still ask for "a template".   I would consider the proposed ToC for chapters as a "template" that chapter teams have to follow.   If you mean that we should provide a "Wiki template", I'm not sure whether it would be a little bit cumbersome ... and at the end difficult to manage.   I bought the benefit of using them for the Backlog Entry Descriptions but I'm not sure for each and every page on our Wiki ... May you provide an example of how that template may look like so that we can play with it a bit ?   On the other hand, don't forget that there are many contributors who don't know the details about the MediaWiki language so that they indeed first write their contribution in Word and then "save as MediaWiki", then do some fine tuning ... We may need to explain what they should do there.

  As for the {{Parameter}} thing, I have to confess that I'm not that an expert on MediaWiki and probably you are right.  However, we again have to take into account that many people will produce their initial input using Word, so therefore we should give them very precise instructions on how to edit the resulting MediaWiki text and add these {{Parameter}} thing.     I sincerely take a look at what you did in your chapters and this is going to be wayyyy difficult to explain and cumbersome to implement.

  Best regards,

-- Juanjo


On 02/02/12 15:58, Leidig, Torsten wrote:

Hi Juanjo,



Now we have at least some guidelines. After looking at some of the existing OpenSpec pages from different chapters I found that no two pages look similar.

So I still recommend to provide a template in order to ensure a common uniform style.



Some comments to the instructions:



You write the target audience are developers of applications or other GEs.



Call me stupid but I still have the feeling that I don't get the meaning of GE concept right.  My understanding is that a GE is describing a general functionality (such as  a "network printing") for which a number of technical realizations can exist (several technical protocols for network printers). So a developer will not use the GE to build applications, he/she rather looks for implementations of the GE which match his/her requirements in terms of non-functional requirements such as cost, interoperability, performance, scalability, SLA, legal, .and so on.



What we actually do in FI-WARE is defining the GE on a level that abstracts from concrete technical realizations. How do we describe GE? I think in terms of their interaction behavior, composition, dependencies, etc. which need to (or may) be provided by a GE implementation. Following this interpretation nobody develops GE, people rather should be able to implement components that conform to GE. The Open Specification must be written in a way to allow developers to implement a GE on its own.



Also no one develops applications on top of GE, applications are developed on top of GE implementations exposing a GE conformant technical interfaces. There could be a catalog of GE implementations that can be used by application developers, which is organized around the GE model. For example as an application developer I look for a implementation of the "Network Printing" enabler, which satisfies my requirement in my situation. Via the catalog (or Marketplace) I can find it.



So an Open Specification for a GE should  only describe what it is used for and how one can interact with it, in a technology neutral way.  It must not prescribe concrete  technical interfaces. Nevertheless, FI-Ware can list or even recommend example technical interfaces in order to harmonize the platform architecture.



In the example of the Apps Repository Enabler I tried to separate the generic part of the GE and the technical part of its implementation by keeping the GE specification neutral and linking to specific technical interfaces (of implementations) at the end of the article.



If this doesn't make sense to you, please take another try to enlighten me.



Regards,

Torsten



PS:

According to the style suggestions you made (italic bold) I recommend to use MediaWiki templates again. I provided and used a couple of them in the Repository pages (e.g. {{Parameter}} ), we could provide more of them. The advantage would be that you can change the rendering and style later without having all people to change every page.







-----Original Message-----

From: fiware-wpa-bounces at lists.fi-ware.eu<mailto:fiware-wpa-bounces at lists.fi-ware.eu> [mailto:fiware-wpa-bounces at lists.fi-ware.eu] On Behalf Of Juanjo Hierro

Sent: Donnerstag, 2. Februar 2012 09:15

To: fiware-wpl at lists.fi-ware.eu<mailto:fiware-wpl at lists.fi-ware.eu>; fiware-wpa at lists.fi-ware.eu<mailto:fiware-wpa at lists.fi-ware.eu>

Subject: [Fiware-wpa] Guidelines section for Architecture Description deliverable available on the Wiki



Hi all,



   I have published a set of guidelines to be followed for the

development of the Architecture Description deliverable:



https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Instructions_on_how_to_develop_FI-WARE_Chapter_Architecture_Descriptions



   This how-to will be enriched during the following days, including a

complete example.   However, I believe it contains already enough

detailed instructions about how to proceed.



   Of course, your feedback is welcome.  Answering your concrete

questions may help to enrich the how-to material.



   Cheers,



-- Juanjo



-------------

Product Development and Innovation (PDI) - Telefonica Digital

website: www.tid.es<http://www.tid.es>

email: jhierro at tid.es<mailto:jhierro at tid.es>

twitter: twitter.com/JuanjoHierro



FI-WARE (European Future Internet Core Platform) Chief Architect



You can follow FI-WARE at:

   website:  http://www.fi-ware.eu

   facebook: http://www.facebook.com/pages/FI-WARE/251366491587242

   twitter:  http://twitter.com/FIware

   linkedIn: http://www.linkedin.com/groups/FIWARE-4239932





Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.

This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at

http://www.tid.es/ES/PAGINAS/disclaimer.aspx

_______________________________________________

Fiware-wpa mailing list

Fiware-wpa at lists.fi-ware.eu<mailto:Fiware-wpa at lists.fi-ware.eu>

http://lists.fi-ware.eu/listinfo/fiware-wpa

.



________________________________
Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at
http://www.tid.es/ES/PAGINAS/disclaimer.aspx
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-wpa/attachments/20120203/673f8975/attachment.html>