[Fiware-wg-leaders] Quick FIWARE Tour Guide for developers and Guidelines for FIWARE Technical Whitepaper (deliverable D.1.1.1 in FI-Core DoW)

[Juanjo Hierro]

Hi all,

  As chapter/wg leaders may have already informed you, we have setup a task force to deal with development of a FIWARE Technical Whitepaper (which indeed matches one of our first delvierables in the FI-Core DoW) that is going to be used in order to produce the contents of the web pages that will work as a bridge between the very introductory pages available when you click on "developers" on the fiware website (leading to http://www.fi-ware.org/developers-entrepreneurs/) and the too detailed non-assisted entries in the FIWARE Catalogue.

  We are going to work in this FIWARE technical Whitepaper using the following shared google doc:
https://docs.google.com/document/d/15bh83haJcH7uRedcqEO_J7Ub89MYQRxjmGWTKZTeEUc/edit?usp=sharing

  Please read the Introduction to understand the philosophy of the document and how it will be used.

  As you can see, it contains a first Table of Contents, including suggested sections for the Quick FIWARE Tour Guide for developers.  In addition, the section on "Development of context-aware applications using FIWARE" has been further developed as a reference.

  Caretakers have been assigned for each of the sections (check comments below the title of each section).   If you are one of them, please take immediate action.   This deliverable is planned by end of November but what really matters more is that we update the contents of the website ASAP because we know, based on feedback received from developers who are approaching FIWARE for their first time, that without creating this "Quick FIWARE Tour Guide for developers" many developers are getting lost and finally give up.

  We would like to close a first draft of this whitepaper by Wednesday November 12th 09:00am, then try to publish those sections that are considered ready for publication on the website.  After that, update the web contents as soon as new sections get ready, making as many updates on the website as needed.

  Best regards,

-- Juanjo


-------- Original Message --------
Subject:        Guidelines for FI-WARE Technical Whitepaper (deliverable D.1.1.1 in FI-Core DoW)
Date:   Mon, 27 Oct 2014 13:31:43 +0100
From:   Juanjo Hierro <juanjose.hierro at telefonica.com><mailto:juanjose.hierro at telefonica.com>
To:     fiware-chapter-leaders at lists.fi-ware.org<mailto:fiware-chapter-leaders at lists.fi-ware.org> <fiware-chapter-leaders at lists.fi-ware.org><mailto:fiware-chapter-leaders at lists.fi-ware.org>, fiware-chapter-architects at lists.fi-ware.org<mailto:fiware-chapter-architects at lists.fi-ware.org>
CC:     fiware-wg-leaders at lists.fi-ware.org<mailto:fiware-wg-leaders at lists.fi-ware.org> <fiware-wg-leaders at lists.fi-ware.org><mailto:fiware-wg-leaders at lists.fi-ware.org>


Hi all,

  As you probably know, one of the most frequently received comments on FIWARE is that we do not provide any easy-to-read, high-level but enough detailed, "starting guide" or "map guide" about FIWARE GEs.   We abruptly transition between a 10.000 Kms of altitude description of FIWARE in [1] to the fully detailed without-holistic-overview-nor-navigation-hint list of GEris in the landing page of the FIWARE Catalogue ([2]).

  This is a rather urgent matter to solve and my intention is that one of our first deliverables in FI-Core, the so-long waited "FIWARE Technical Whitepaper", is precisely focused to solve this issue.

  This means that the FIWARE Technical Whitepaper will be developed as to become the web pages that will be intermediate between [1] and [2].   Its contents will, on the other hand, be referred from the FAQ (Frequently Asked Questions) now available at [3] as to make sure, one way or the other, a developer lands in these web pages when (s)he first approaches FIWARE and the FIWARE website.

  A shared google docs will be distributed this week with the table of contents of the FIWARE Technical Whitepaper.   A general overview section and a number of sections will already be completed as a reference.   Then, your contribution will be requested to cover concrete sections so please stay tuned and react quickly.   Contents of each section should establish the links to the entries describing specific GEris in the FIWARE Catalogue based on the introduction provided.   Sections will be defined not following a chapter-by-chapter + GE-by-GE description but trying to introduce scenarios which ring the bells of the developer ("Oh, I want to solve that matter so now I know what FIWARE can do for me and what GEris to further analyze for that purpose").    Therefore, sections will look more like "Creating Context-Aware applications" or "Managing authorization and access control to APIs" ...

  Answer to the question "What kind of things can FIWARE do for me?" in the FAQ (see [4]) can give you an insight about how the general overview section of the whitepaper may look like.

  Somehow, the FIWARE Technical Whitepaper should enable us to complete the "Tour Guide" for FIWARE.  FIWARE is like a city where developers will land.  The Whitepaper will work as those contents of the tour guide where it explains where to go based on your goals "if you want to do <X> ... then sure you will enjoy <A>" or the description of given areas/zones of the city (typically linked to suggested journeys) are provided.   Chapters in a Tour Guide may lead finally to very detailed descriptions of concrete locations but only after a general recommendation on areas/zones to visit where the concrete locations can be found.   Now, we don't provide such a tour guide in our site and that is what is missing.   We just provide the glossary (in alphabetical order) of the Tour Guide and the detailed description of concrete locations!   Would you be able to organize yourself when visiting a city for your first time with such a Tour Guide ?   Clearly not.

  Once the contents of this FIWARE Technical Whitepaper is available (maybe even once some enough complete drafts of them are available, since it is urgent), we will perform some updates of our website:

  *   Page [1] will be updated so that a quick overview (maybe a summary of the overview section) is provided as content of a new section titled "What kind of things can FIWARE do for you?" right before that part of the page currently under the title "Wanna start quickly using FIWARE?".   This new section will lead to the contents of the web pages with the contents of the Technical Whitepaper which should become the new landing page of the Catalogue (replacing contents currently at [5]).
  *   Contents currently under the "Wanna start quickly using FIWARE?" title will be located after the quick overview section or even probably after the section under the title "FIWARE Catalogue: useful components to start with".
  *   Note that we will hide direct access to [2] which was a mere listing of GEris that far from help, it led to confusion because there was no "journey/tour" suggested to the developer.

  This is all for the moment.   As mentioned, please keep tuned because there will immediate actions to perform.    Anyways, let's discuss this during the confcall today.

[1] - http://www.fiware.org/developers-entrepreneurs/
[2] - http://catalogue.fiware.org/enablers
[3] - http://wiki.fi-ware.org/FIWARE_Frequently_Asked_Questions_(FAQ)<http://wiki.fi-ware.org/FIWARE_Frequently_Asked_Questions_%28FAQ%29>
[4] - http://wiki.fi-ware.org/FIWARE_Frequently_Asked_Questions_(FAQ)#What_kind_of_things_can_FIWARE_do_for_me.3F__How_can_I_incorporate_FIWARE_gradually.3F<http://wiki.fi-ware.org/FIWARE_Frequently_Asked_Questions_%28FAQ%29#What_kind_of_things_can_FIWARE_do_for_me.3F__How_can_I_incorporate_FIWARE_gradually.3F>
[5] - http://catalogue.fiware.org


  Best regards,


-- Juanjo
-------------
Telefonica - Product Development and Innovation (PDI)
website: www.tid.es<http://www.tid.es>
email: juanjose.hierro at telefonica.com<mailto:juanjose.hierro at telefonica.com>
twitter: twitter.com/JuanjoHierro

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

You can follow FI-WARE at:
  website:  http://www.fi-ware.org
  facebook: http://www.facebook.com/pages/FI-WARE/251366491587242
  twitter:  http://twitter.com/FIware
  linkedIn: http://www.linkedin.com/groups/FIWARE-4239932





________________________________

Este mensaje y sus adjuntos se dirigen exclusivamente a su destinatario, puede contener información privilegiada o confidencial y es para uso exclusivo de la persona o entidad de destino. Si no es usted. el destinatario indicado, queda notificado de que la lectura, utilización, divulgación y/o copia sin autorización puede estar prohibida en virtud de la legislación vigente. Si ha recibido este mensaje por error, le rogamos que nos lo comunique inmediatamente por esta misma vía y proceda a su destrucción.

The information contained in this transmission is privileged and confidential information intended only for the use of the individual or entity named above. If the reader of this message is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this transmission in error, do not read it. Please immediately reply to the sender that you have received this communication in error and then delete it.

Esta mensagem e seus anexos se dirigem exclusivamente ao seu destinatário, pode conter informação privilegiada ou confidencial e é para uso exclusivo da pessoa ou entidade de destino. Se não é vossa senhoria o destinatário indicado, fica notificado de que a leitura, utilização, divulgação e/ou cópia sem autorização pode estar proibida em virtude da legislação vigente. Se recebeu esta mensagem por erro, rogamos-lhe que nos o comunique imediatamente por esta mesma via e proceda a sua destruição
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-wg-leaders/attachments/20141107/0c121ed1/attachment.html>