From bfd6cd27ca935156cf82d6df0a61ef4a700ebdb2 Mon Sep 17 00:00:00 2001
From: "j.goderbauer" <j.goderbauer@adito.de>
Date: Tue, 1 Oct 2019 15:45:05 +0200
Subject: [PATCH] Contact_entity: extended documentation

---
 entity/Contact_entity/documentation.adoc | 32 +++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/entity/Contact_entity/documentation.adoc b/entity/Contact_entity/documentation.adoc
index 0d02f16097..8a1f2ff916 100644
--- a/entity/Contact_entity/documentation.adoc
+++ b/entity/Contact_entity/documentation.adoc
@@ -1,3 +1,33 @@
 = Contact_entity
 
-Represents a Contact without detail information to Organisations/Persons
\ No newline at end of file
+WARNING: Do not confuse this entity with the `Person_entity`. The `Person_entity` is the representation of a person-contact, 
+while the `Contact_entity` is used for further contacts from a perspective of a single person-contact.
+
+Represents a Contact without detail information to Organisations/Persons and is used for displaying and creating
+further (=other) contacts in correlation of a single person-contact.
+
+== Example:
+A person (not a person-contact but a person) has in summary 3 contacts:
+
+- Person: "Maddison Shepard"
+- Person-contact in Organisation "MUX Ltd."
+- Person-contact in Organisation "Shepard Ships Org"
+- Person-contact as a private person
+
+From _Maddison Shepard @ MUX Ltd._'s perspective you can see the further contacts 
+_Maddison Shepard @ Shepard Ships Org_
+and the 
+_private person Maddison Shepard_.
+
+
+From _Maddison Shepard @ Shepard Ships Org_'s perspective you can see the further contacts 
+_Maddison Shepard @ MUX Ltd._
+and the 
+_private person Maddison Shepard_
+and so on.
+These "further contacts" is what the Contact_entity actually is. (this corresponds both display and modifying-mode)
+
+== Why another entity?
+You only want to create a new entry within the `CONTACT`-db-table but not in the `PERSON`-db-table when creatging a new [further] contact
+to an existing person-contact. But - right now - it's only possible to set the "readonly" property within a db-record-container per table as a static configuration but not dynamically.
+This is the reason why we've got to use a very similar but more basic entity where the `PERSON`-db-table is _readonly_ (=the `Contact_entity`).
\ No newline at end of file
-- 
GitLab