From 6724c527a653ad3842994ef400bae98fd5d55804 Mon Sep 17 00:00:00 2001
From: Michael Gaffney <mgaffney@users.noreply.github.com>
Date: Sun, 11 Oct 2020 15:05:15 -0400
Subject: [PATCH] Docs: add content to Domain Model - Groups page (#618)

---
 .../docs/concepts/domain-model/groups.mdx     | 77 +++++++++----------
 1 file changed, 37 insertions(+), 40 deletions(-)

diff --git a/website/content/docs/concepts/domain-model/groups.mdx b/website/content/docs/concepts/domain-model/groups.mdx
index ba435e8473..198b965601 100644
--- a/website/content/docs/concepts/domain-model/groups.mdx
+++ b/website/content/docs/concepts/domain-model/groups.mdx
@@ -8,43 +8,40 @@ description: |-
 
 # Groups
 
-Groups are collections of Users used only for access control purposes.
-A Group is owned by one and only one Scope.
-A Group can contain zero or more Users.
-A Group inherits from Principal ("is-a" Principal)
-allowing it to be associated with zero or more Roles.
-All Users in a Group are granted the capabilities of all Roles the Group is associated with.
-A Group is deleted when the Scope it belongs to is deleted.
-The lifecycle of a Group is not tied to the lifecycle of any User or Role.
-
-```shell-session
-+-------------------------------------+
-|           Organization              |
-+--------------------------+----------+
-| Group 1                  | Group 2  |
-+--------+--------+-------------------+
-| User 1 | User 2 | User 3 | User 4   |
-+--------+--------+--------+----------+
-```
-
-# Attributes
-
-### ID
-
-A group ID has a `g_` prefix followed by ten digits.
-
-Example: `g_0123456789`
-
-### Name
-
-A group name is the friendly name of a group resource.
-
-### Description
-
-A group description is the friendly description of the group resource.
-
-# Referenced By
-
-- [User]()
-- [Role]()
-- [Organization]()
+A group is a resource
+that represents a collection of [users][]
+which can be treated equally
+for the purposes of access control.
+A group is a principal
+which allows it to be assigned to [roles][].
+Any role assigned to a group is indirectly assigned to the users in the group.
+This assignment is a transitive property.
+A user in a group receives all [permissions][] of the roles assigned to the group.
+Groups can be defined at either a [Global][] or [Organization][] [scope][].
+
+## Attributes
+
+A group has the following configurable attributes:
+
+- `name` - (optional)
+  If set, the `name` must be unique within the group's immediate parent [scope][].
+
+- `description` - (optional)
+
+## Referenced By
+
+- [Global][]
+- [Organization][]
+- [Role][]
+- [User][]
+
+[global]: /docs/concepts/domain-model/scopes#global
+[group]: /docs/concepts/domain-model/groups
+[groups]: /docs/concepts/domain-model/groups
+[organization]: /docs/concepts/domain-model/scopes#organizations
+[permissions]: /docs/concepts/security/permissions
+[role]: /docs/concepts/domain-model/roles
+[roles]: /docs/concepts/domain-model/roles
+[scope]: /docs/concepts/domain-model/scopes
+[user]: /docs/concepts/domain-model/users
+[users]: /docs/concepts/domain-model/users