Improve documentation

README.md

@@ -33,7 +33,8 @@ This repository forms part of the Eiffel Community. Eiffel is a protocol for tec
 Visit [Eiffel Community](https://eiffel-community.github.io) to get started and get involved.
 
 # Contents
-1. [Introduction](./introduction/introduction.md)
+1. Introduction
+   1. [Introduction](./introduction/introduction.md)
    1. [How to Propose Changes and Contribute](https://github.com/eiffel-community/.github/blob/master/CONTRIBUTING.md)
    1. [Code of Conduct](https://github.com/eiffel-community/.github/blob/master/CODE_OF_CONDUCT.md)
 1. Eiffel Syntax and Usage

customization/custom-data.md

@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017 Ericsson AB.
+   Copyright 2017-2022 Ericsson AB.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -27,5 +27,20 @@ While __data.customData__ affords users extensive freedom in including custom co
 * Are there existing Eiffel events and/or event members able to express the information? Using the standard vocabulary and syntax should always be the first option.
 * If your use case lacks support in the standard Eiffel vocabulary, there's a chance this is actually a general use case which deserves such support. Create an [Issue](https://github.com/eiffel-community/eiffel/issues) about it! It is always better to design a common solution than to implement multiple local adaptations.
 * Users defining __data.customData__ members are responsible for them and any compatibility issues. Special considerations or support from standard Eiffel events or syntax cannot be expected, unless the custom syntax is proposed to and accepted into the standard Eiffel vocabulary (and consequently is no longer custom).
+* Do you aggregate data on the producer side and add that data as custom data? If
+  the producer aggregates the data it will do so for a specific consumer but we
+  want to create a protocol that can serve any consumer for use cases that has not
+  yet seen the light. Try to use the existing fields and aggregate data
+  on the consumer side.
+* Do you give too much data? The maintainers of the protocol have reviewed the
+  protocol as a whole, making consideration on data security.
+* Do you use Eiffel to solve a generic data streaming problem? Eiffel provides
+  a semantic for describing occurrencies in a CI/CD system and use links when
+  needed to point to more information.
+* Can you describe properly what data to send in the new parameter? The Eiffel
+  protocol specifies what data to send in each event.
+* Can you ensure the same use of the new parameter in all places?
+* If you send the same data in more than one member? Which one do you read?
+* Have you provided a good enough context for the reader to understand the data?
 
 The [event design guidelines](../eiffel-syntax-and-usage/event-design-guidelines.md) shall be observed with regards to key and value naming conventions.

eiffel-syntax-and-usage/event-design-guidelines.md

@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017 Ericsson AB.
+   Copyright 2017-2022 Ericsson AB.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -34,3 +34,32 @@ The design of Eiffel events is governed by the following guidelines:
 * __Key names in camelCase:__ All key names shall use camelCase.
 * __Enumerations in CAPS_WITH_UNDERSCORE:__ All enumerated values shall use CAPS_WITH_UNDERSCORE.
 * __Link types are nouns:__ Link types shall have names that fit the pattern "\<target event> is the \<source event>'s \<link type>", implying that they are nouns that describe the relationship between the source and the target event.
+
+## Benefits and Implications
+
+By following the design guidelines the Eiffel protocol provides a language that
+gives producers and consumers a common way of understanding and describing the
+occurrences in the system by defining a contract between them.
+
+Following the guidelines stated, they address the following issues:
+
+* __Protocol variants__: By using the protocol it gives the best possible
+  conditions for non-initiated event consumers to make sense of any given set of
+  events.
+* __Inconsistency__: By providing clear explanations of each member for both
+  producers and consumers it minimizes the risk for both data divergence and
+  inconsistency.
+* __Coordination__: The Eiffel protocol minimizes coordination efforts between
+  producers and consumers by providing a well-defined specification that the
+  parties can use as a contract.
+* __Context__: Following the protocol gives each data a clear context to which it
+  belongs.
+* __Tight coupling__: By using the Eiffel protocol specification it reduces the
+  risk of creating hard connections between producers and consumers. We want to
+  enable adding new consumers without affecting the producers. This then leads to
+  a decoupled system with separation of concerns that enables scalability and
+  maintainability.
+
+When using Eiffel as described it creates a data model based on information
+nodes and semantics links between these nodes. To read this you will need a tool
+to aggregate the information.

introduction/introduction.md

@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2019 Ericsson AB and others.
+   Copyright 2017-2022 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,6 +19,22 @@
 
 This page provides an introduction to Eiffel: what is it, why is it and who is it for?
 
+<!-- TOC -->
+
+- [Introduction](#introduction)
+  - [Why Eiffel?](#why-eiffel)
+  - [What is Eiffel?](#what-is-eiffel)
+  - [Who Developed Eiffel?](#who-developed-eiffel)
+  - [Who Should Use Eiffel?](#who-should-use-eiffel)
+  - [How Do I Get Started?](#how-do-i-get-started)
+  - [How is Eiffel Technology Agnostic?](#how-is-eiffel-technology-agnostic)
+  - [How Does Eiffel Achieve Scalability?](#how-does-eiffel-achieve-scalability)
+  - [How Does Eiffel Achieve Flexibility?](#how-does-eiffel-achieve-flexibility)
+  - [How Does Eiffel Achieve Traceability?](#how-does-eiffel-achieve-traceability)
+  - [How Do I Make Sense of Events?](#how-do-i-make-sense-of-events)
+
+<!-- /TOC -->
+
 ## Why Eiffel?
 As software products steadily increase in size and complexity, so do the systems that ultimately build, test, package and deploy those products: our continuous integration and delivery systems. It is not uncommon for these systems to span entire enterprises with thousands of engineers in various roles, integrating and testing solutions in intricate webs of dependencies and causality. Historically, this has been a process management problem, but with increasing demands for speed and automation it is rapidly transforming into a software engineering problem.
 
@@ -27,7 +43,7 @@ Furthermore, it is a software engineering problem that can scarcely be solved by
 The Eiffel philosophy is to treat the continuous integration and delivery system just like any other complex and constantly changing software system, and apply the same architectural thinking. In Eiffel that new acquisition or those rebellious developers can have their cake and eat it, too. Heterogenous tools and processes are allowed to co-exist by applying a thin layer of glue on top of it all, focusing on the essential pieces of information we need in order to collaborate. And, analogous to a microservices oriented system, various services can then be added on top of that glue to store, process, analyze, visualize and act upon those essential pieces of information, affording you transparency across the enterprise.
 
 ## What is Eiffel?
-Eiffel is a framework for continuous integration and delivery, particularly addressing the challenges of a distributed and heterogeneous environment at an enterprise scale. It does this through the _in situ_ real time generation of globally broadcast events - events which reference one another, forming a Directed Acyclic Graph (DAG) describing all the activities of the continuous integration and delivery pipeline, regardless of where they took place, which underlying technology they used, or even whether they were automated or not. 
+Eiffel is a framework for continuous integration and delivery, particularly addressing the challenges of a distributed and heterogeneous environment at an enterprise scale. It does this through the _in situ_ real time generation of globally broadcast events - events which reference one another, forming a Directed Acyclic Graph (DAG) describing all the activities of the continuous integration and delivery pipeline, regardless of where they took place, which underlying technology they used, or even whether they were automated or not.
 
 Eiffel fundamentally consists of two parts. First, a vocabulary and syntax of events, forming the communication protocol of the framework. Second, services built on top of that communication protocol to orchestrate continuous integration and delivery activities, provide traceability, dashboards, visualizations and much more.
 
@@ -40,7 +56,7 @@ Eiffel is technology and domain agnostic - it may be applied equally well to the
 ## How Do I Get Started?
 To use Eiffel you need three things: the Eiffel vocabulary, messaging infrastructure and services operating on, storing and analyzing your Eiffel events.
 
-The Eiffel vocabulary can be adopted incrementally - which events you use is up to you, but _how_ they are used is heavily standardized to ensure interoperability and alignment on proven practices. 
+The Eiffel vocabulary can be adopted incrementally - which events you use is up to you, but _how_ they are used is heavily standardized to ensure interoperability and alignment on proven practices.
 
 There are several valid out-of-the-box solutions for event transport and routing infrastructure, depending on your needs and preferences. Examples include [RabbitMQ](https://www.rabbitmq.com/), [Kafka](http://kafka.apache.org/), [NATS](http://nats.io/) and more. When choosing infrastructure, it is important to understand the implications of the different types of guarantees these solutions can offer. While some provide durable queues and delivery guarantees, others do not, but instead offer higher performance. It is important to consider one's requirements and choose the appropriate solution for event transport and routing accordingly; to maximize reliability and traceability capabilities, it is generally recommended to choose a solution with durable queues and delivery guarantees.
 
@@ -56,7 +72,7 @@ Eiffel is not a centralized or monolithic tool. Instead it represents a decentra
 * It removes centralized continuous integration servers as bottlenecks.
 
 ## How Does Eiffel Achieve Flexibility?
-An important principle in Eiffel is that events are not prescriptive, but descriptive. An event is not an RPC call, it will not order the recipient to take a certain action. Instead, it is assumed that the recipient will react in an intelligent and conducive manner to the information it gathers. Holding to this principle becomes particularly important in large, multi-organizational integration contexts, as it allows decoupling and separation of concerns between consumers and producers of events. 
+An important principle in Eiffel is that events are not prescriptive, but descriptive. An event is not an RPC call, it will not order the recipient to take a certain action. Instead, it is assumed that the recipient will react in an intelligent and conducive manner to the information it gathers. Holding to this principle becomes particularly important in large, multi-organizational integration contexts, as it allows decoupling and separation of concerns between consumers and producers of events.
 
 To exemplify, an organization developing a common component does not - and indeed should not - need to know how the continuous integration systems of its consumers are set up. As long as it accurately report on its own process as it builds, tests and verifies new versions consumers may come and go, or may decide to pick up specific deliveries or not, for any reason, without any need to notify or synchronize with the developing organization. Despite this traceability is still preserved: looking up who has integrated which component version when, how long it took, and whether they are included in any customer releases is but a query away.