[Fiware-wpa] FI-WARE-review Proposal for the Resubmission of Open Specifications

[Juanjo Hierro]

Dear Uwe and Thorsten,

  Thanks for your valuable input.  I rather appreciate this kind of pro-activeness in providing constructive concrete proposals (like this one) as compare to simply ranting about what is being proposed.

  It is nice because your proposal seems to be based on the same premise I was starting to suspect was right after recently carefully reviewing once again the review report, looking at some early results of some of the peer reviewers and considering what we have there on the public Wiki: Regarding specifications of each FI-WARE GE, I suspect that the reviewers were expecting something which could have been well covered by just delivering together (in the same document deliverable) the architecture description of the GE with the specifications of the APIs linked to that GE.

  This suspicion is somehow confirmed based on an informal conversation a third party (allow me not to disclose the source :-) has recently had with Arian.   During this conversation, it seems like he was claiming that "Open Specifications of a given GE cannot be two pages long as they are" ...  apparently Arian (and reviewers) didn't get the point that what we submitted was just the API specifications ...  Because anyone reading those specifications was expected to have read the architecture description of the GE before.   This person explained that the complete specifications of a FI-WARE GE was indeed made of the architecture description plus the Open API specifications and this apparently was a view that Arian hadn't taken into consideration (this was the feedback this person that talked to him has given to me).

  Assuming this is correct, it actually makes sense to "regenerate" the Open Specifications deliverable so that we "embed" the architecture description of each FI-WARE GE as part of the "Open Specifications of that GE".    I thought this was actually difficult to implement because I though that Mediawiki didn't have any sort of "include" directive ... but you seem to have found the technical solution by means of using the {{:page_name_of_the_architecture_description}} functionality ... Great !!

  However, before taking a final decision and jumping on this direction, I would like to raise the following points and gather your feedback:

  *   Do you believe that this is easier than trying to explain Arian and reviewers how the Architecture and Open Specification documentation was indeed structured in order to change their perception ?    I tend to agree and think "let's not waste our time explaining how and why we had done things like we did, just give them what they want to see" ... However:
  *   There is the risk that they realize that we were "copying" contents from one place to another (well, indeed referring inline) and then they come back to us saying "Hey ! you were trying to cheat us and spare efforts by copying things that belong to another deliverable" ...  Do we like to risk that much ?
  *   My answer would be that we shouldn't risk and, no matter whether we decide to go for adopting the new template, we should explain our view on the matter and tell them ... "look, this is the rationale of what we did and how you could collect the complete specification of a GE, but we can implement this artifact if that is more suitable to you so that one way or another you will get a complete specification".   I believe one benefit of giving this explanation is that they hopefully would realize that we didn't do things that bad as they thought.

  Given said all this, we still need to finalize the peer review we are doing and start a second review.   The feedback that I have got from some reviewers is that we also had many things to improve content-wise, so it is not ONLY a matter of "formatting" of the deliverable.    What we need to agree on is whether the second review to carry out is something we should after adopting a template like the one you suggested or not.   At a minimum, we should instruct peer reviewers to review the architecture description and API open specifications of each GE all together as part of the target complete specification.

  Comments/views are welcome.

  Cheers,

-- Juanjo





On 26/09/12 16:17, Riss, Uwe wrote:
Hi all,

Actually I had planned to raise an additional issue in the WPL/WPA call yesterday, however, due to the other pressing topics there had not been enough to discuss it. Therefore I distribute it offline. Our suggestion concerns the following points:


1.       We suggest to proactively adopted the central points raised by the reviewers by providing a new template & example page that addresses the issues. The new page is: https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Open_specification_resubmission_template the example page can be reached from this page by a link.

The work is not finished and not all of the content in the example is stable, but due to timing constraints we would like to now start the discussion

2.       on the following requirements, at which the new template is particularly aiming:

a.       Every open specification should be self contained

b.      Target audience is not only users, but as well people providing implementations of GEs, based on their open specifications

c.       Scope, behavior and intended use is documented

d.      Clear IPR statements & legal notices

3.       We assume the proposed changes to be rather small and therefore we see a substantial chance that we might be able to implement them in due time quickly enough.

4.       For the overall submission there needs to be a separate Adoption of the book-template, which would include as well standard sections like "Introductions" and "Appendixes" (details will follow)

5.       It would not be possible to compile this template in such a quick way, without the great work that the TID team has already carried out.



6.       Finally: There is a number of inconsistencies in the guidelines of currently in the FI-WARE-private wiki - these should be updated/marked as deprecated or deleted after consensus is found. https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Where_and_how_to_publish_Open_Specifications  https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Common_aspects_in_FI-WARE_Open_Restful_API_Specifications https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/RESTful_API_specification_template

The rationale behind these suggestions is that the reviewers clearly articulated that the Open Specifications in the submitted format were not sufficient in relation to the content being promised in the FI-WARE DoW. We regard this as one of the reasons why they were rejected and budget cuts were implemented. We analyzed the situation and come to the following conclusions:

1.       The requirements stated in the DoW and outlined by the reviewers have to be accepted and subsequently there needs to be a resubmission in relation to the given criteria ASAP, if not until M18

2.       The current submission included only the RESTful-API pages which lead to the situation that in deed there were major differences in proposed vs. submitted content

3.       Although stated as planned in https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Instructions_on_how_to_develop_FI-WARE_Chapter_Architecture_Descriptions: "the Architecture deliverable will become an integral part of the final GE open specifications", this has never been submitted in this format to the commission, which finally lead to the bad review in relation to the this topic

4.       We fear that even the 2nd review of the Open Specification is currently not sufficiently addressing major changes in the content and resubmission of the open specifications

5.       Most of the requested content is already present in the wiki or in subsequent pages, but was not compiled in the right way and references was often missing.



We hope to start a productive offline discussion by making these suggestions and hope for your feedback. Otherwise if you do not bring forward arguments against this suggestions we would assume that you generally agree with them and further urge for their implementation.


Best regards,

Thorsten & Uwe


Dr. Uwe Riss
Senior Researcher, Internet Applications & Services   |   SAP Research Karlsruhe
SAP AG   |   Vincenz-Priessnitz-Str. 1   |   76131 Karlsruhe   |   Germany

T +49 6227 7-70212   |   F +49 6227 78-26158   |   M +49 151 16810936   |   mailto: uwe.riss at sap.com<mailto:uwe.riss at sap.com>
www.sap.com<http://www.sap.com/>

Pflichtangaben/Mandatory Disclosure Statements: http://www.sap.com/company/legal/impressum.epx

Diese E-Mail kann Betriebs- oder Geschaeftsgeheimnisse oder sonstige vertrauliche Informationen enthalten. Sollten Sie diese E-Mail irrtuemlich erhalten haben, ist Ihnen eine Kenntnisnahme des Inhalts, eine Vervielfältigung oder Weitergabe der E-Mail ausdruecklich untersagt. Bitte benachrichtigen Sie uns und vernichten Sie die empfangene E-Mail. Vielen Dank.

This e-mail may contain trade secrets or privileged, undisclosed, or otherwise confidential information. If you have received this e-mail in error, you are hereby notified that any review, copying, or distribution of it is strictly prohibited. Please inform us immediately and destroy the original transmittal. Thank you for your cooperation.



________________________________

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/20120926/6a9535dd/attachment.html>