WIP: documentingsandbox/jobol/doc

Change-Id: Ica30d4ae05e0541e6dd4ed0292cb16abab461269

1 files changed, 32 insertions, 4 deletions

diff --git a/docs/2-widgets.md b/docs/2-widgets.md
index 2a7972e..6b76027 100644
--- a/docs/2-widgets.md
+++ b/docs/2-widgets.md
@@ -1,7 +1,35 @@
 # The widgets
 
-The widgets are described by the W3C's technical recommendations
-[Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) and [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig)
+Applications are packaged and delivered in a digitally signed container
+named *widget*. A widget contains:
+
+- the application and its data
+- a configuration file *config.xml*
+- signature files
+
+The format of widgets is described by W3C (World Wide Web Consortium)
+technical recommendations:
+
+- [Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets)
+  (note: now deprecated)
+
+- [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig)
+
+Note that the technical recommendation
+[Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets)
+is now obsolete (since 11 october 2018).
+It implies that a new format of widgets can be proposed in replacement.
+
+
+The format is enough flexible to include the description of permissions
+and dependencies required or provided by the application.
+
+Signature make possible to allow or deny permissions required by the
+application based on certificates of signers.
+
+A chain of trust in the creation of certificates allows a hierarchical
+structuring of permissions.
+
+It also adds the description of dependency to other service because AGL
+programming model emphasis micro-services architecture design.
 
-In summary, **widgets are ZIP files that can be signed and
-whose content is described by the file <config.xml>**.