Feedback on CO310

_episodes/01-COperson.md

@@ -16,20 +16,20 @@ People are represented in COmanage by a `CO Person`:gear: object. Some informati
 
 The attributes (information) stored in the `CO Person`:gear: object typically includes
 
-* The organization or collaboration of which the person is a part (in the form of an identifier)
+* The virtual organization or collaboration of which the person is a part (in the form of an identifier _sort of, but it's really in the form of a CO Person Role_)
 * The person's status within that organization or collaboration
-* Minimal information about the person including the person's preferred time zone and date of birth, list of physical addresses.
+* Minimal information about the person including the person's (_preferred time zone is really a technical thing, time zone is ordinarily automatically determined_) date of birth, list of physical addresses.
 * List of names
 * List of identifiers
 * List of email addresses
-* list of physical addresses
+* (list of physical addresses _duplicate_)
 
 This object also is connected to several other structural items that we will talk about in this lesson, including
 
 *  **External Representations** - representations of the person in other contexts outside of COmanage (including real life!) These representations include attributes and information about the person related to the other context. Each `CO Person`:gear: must have at least one of these, though multiple are allowed.
 * **Roles** - the roles that the person assumes within your organization.
 * **Group Memberships** - membership in a specific COmanage organizational object called a :gear" `CO Group`. We will learn more about :gear" `CO Groups` in a later lesson.
-* **Authenticators** - methods for the person to sign into COmanage
+* **Authenticators** - methods for the person to sign into services
 
 ---
 
@@ -41,6 +41,8 @@ The status value will affect what someone is able to do, including affecting wha
 
 Below is a table of the available statuses _< NOTE: This list should be simplified somehow - some of these statuses aren't really used for CO person, but are interim status during the enrollment flow - should include only the 'stable' status that a CO Person remains in for longer durations. For the others, we can allude to them, and explain them more fully where they are actually used. >_
 
+_I think you can focus on Active/GracePeriod/Suspended/Expired_
+
 Preference | Status | Description
 ---------- | ------ | -----------
 1 | Active | Person or Role is an active member of the organization or collaboration
@@ -66,13 +68,15 @@ Each `CO Person`:gear: object must include the person's name. `CO Person`:gear:
 
 _< NOTE: Laura wrote this section, but isn't sure about her understanding of identifiers for CO Person. From the documentation it sounds like the recommendation is to have one CO Person identifier that is auto assigned, and for this identifier to be used for provisioning to at least some kinds of services rather than tying that provisioning to an org identity (like eppn) that may change if affiliation does. BUT... this may be totally wrong. >_
 
+_The ultimate goal of identifiers is to faciliate application integration. Scott has a good document on this in the wiki._
+
 Identifiers allow for unique identification. In COmanage, each `CO Person`:gear: may be associated with [an?] identifier[s?]. [These identifiers | The identifier] can be important when provisioning services to `CO Persons`:gear:.
 
 We recommend that you configure at least one identifier for each `CO Person`:gear: to represent the person within COmanage. While it is possible to manually assign identifiers, we suggest that you allow COmanage to automatically assign these identifiers. You are able to configure what these identifiers will look like.
 
 # About email address attributes
 
-COmanage can track email addresses, though it does very little with them directly. Email addresses can be verified from within COmanage (which we will not review during this workshop). Email addresses can also be used for mailing lists using the mailman provisioner (which we will review, time allowing.)
+COmanage can track email addresses, though it does very little with them directly (_well we now have email list support, and we send notifications to them, but often they're provisioned - perhaps via LDAP - to downstream applications_). Email addresses can be verified from within COmanage (which we will not review during this workshop). Email addresses can also be used for mailing lists using the mailman provisioner (which we will review, time allowing.)
 
 When storing email addresses, more than one can be associated with the `CO Person`:gear:, and can contain a type to help distinguish the conditions under which to use each. For example,
 
@@ -83,7 +87,7 @@ When storing email addresses, more than one can be associated with the `CO Perso
 
 # About physical address attributes
 
-This information is not used by COmanage, but since it is handy to have physical address information in your registry, it is included. Any number of physical addresses may be associated with a :gear" `CO Person` object.
+This information is not used by COmanage, but since it is handy (_eg: to provision to your organization's directory_) to have physical address information in your registry, it is included. Any number of physical addresses may be associated with a :gear" `CO Person` object.
 
 ---
 

_episodes/02-orgIdentity.md

@@ -17,7 +17,7 @@ Because people in COmanage are represented by `CO Person`:gear: objects, it is h
 The attributes (information) stored in `Org Identity`:gear: objects typically includes
 
 * Link to `CO Person`:gear: object
-* Status
+* Status (_the OrgIdentity status isn't really used to reflect external status as we rarely get that sort of information; this field is really to denote the status of the OrgIdentity wrt its OrgIdentitySource, if any_)
 * Personal information about the person
   * Date of birth
   * affiliation (eduPerson)
@@ -30,8 +30,8 @@ The attributes (information) stored in `Org Identity`:gear: objects typically in
 
 This object also is connected to several other structural items that we will talk about in this lesson, including
 
-* **Source Information** - represented by an `Identity Source`:gear: object, this item contains details about how the source should be processed and the data gathered from the representation of the person at the source.
-* **Cached Source Information** - represented by an `Identity Source Records`:gear: object, this item connects the `Identity Source`:gear: to the `Org Identity`:gear:, and is also used to cache data in COmanage from sources so that they are readily available.
+* **Source Information** - represented by an `Organizational Identity Source`:gear: object, this item contains details about how the source should be processed and the data gathered from the representation of the person at the source.
+* **Cached Source Information** - represented by an `Organizational Identity Source Records`:gear: object, this item connects the `Organizational Identity Source`:gear: to the `Org Identity`:gear:, and is also used to cache data in COmanage from sources so that they are readily available.
 
 --- 
 
@@ -43,30 +43,32 @@ These lists of items are handled similarly to how they are used for `CO Person`:
 
 _< NOTE: Laura wrote this section, but isn't sure about her understanding of identifiers for Org Identity. The information here may be totally wrong. >_
 
+(_They're basically the identifiers asserted from the source. Most typically they'll be eppn/eptid_)
+
 `Org Identity`:gear: objects also use identifiers. The identifiers can be one of several different types
 
 * eppn: eduPersonPrincipalName
 * eptid: eduPersonTargetedID
 * mail: RFC 4524
 * openid: OpenID
 * uid: RFC 4519 uidObject (previously userid)
-* Or an extended type that is specific to the source related to the `Org Identity`:gear:
+* Or an extended type that is specific to the source related to the `Org Identity`:gear: (_At the moment this isn't actually supported_)
 
 ## Identifiers for authentication
 
 Identifiers attached to `Org Identity`:gear: objects can potentially be used for signing into COmanage. A flag set on the identifier will indicate if it is used for sign in.
 
 ---
 
-Now we'll talk about sources - information from external systems - and how they are captured and used in COmanage.
+Now we'll talk about (_Probably best to use the formal name at least once: Organizational Identity_) sources - information from external systems - and how they are captured and used in COmanage.
 
 # The relationship between `Org Identity`:gear: objects and **sources**
 
 The `Org Identity`:gear: object is related to the source where its information came from. Often the source is from an external system, like LDAP, an authentication system, ORCID or even a CSV file. COmanage keeps track of this source for several reasons:
 
 * for auditing where information about a person came from
 * for syncing with external systems to get the most up-to-date information
-* to connect for performing actions that may happen outside of COmanage, for example, federated authentication.
+* to connect with actions that may happen outside of COmanage, for example, federated authentication.
 * to provide information about the person provisioning access and privileges to external ("outbound") systems.
 
 COmanage has built-in capability to consume data and attributes from many of these sources, and can be extended to support additional sources. This information is managed through `Identity Source`:gear: objects and their COmanage-cached versions, `Identity Source Record`:gear: objects. 

_episodes/04-permissions.md

@@ -31,16 +31,16 @@ Some groups for managing these permissions are created automatically when config
 
 # Guest permissions
 
-COmanage allows you to configure it to let people who are not fully registered (guests) to see some information stored on the platform (for example, a person directory or list of groups.) The platform also enables you to allow guests to create their own accounts (self enroll), for example, to join a group for a mailing list or to access specific resources. We will talk more about these capabilities in a later lesson about enrollment workflows.
+COmanage allows you to configure it to let people who are not fully registered (guests) to see some information stored on the platform (for example, a person directory or list of groups.) (_What specifically is being referred to here? Guests is an ambiguous term - Registry itself has no such defined concept. Users either have permission to do something or they don't._) The platform also enables you to allow guests to create their own accounts (self enroll), for example, to join a group for a mailing list or to access specific resources. We will talk more about these capabilities in a later lesson about enrollment workflows.
 
 # Self Service Permissions
 
 COmanage allows certain attributes (information) to be managed by users directly.
 
 ## Attributes always available for self service
 
-* `CO Person`:gear: NSF Demographic attributes (an optional COmanage component)
-* `CO Person`:gear: Preferred Timezone
+* `CO Person`:gear: NSF Demographic attributes (an optional COmanage component) (_maybe omit this? nobody really uses it and we'll probably deprecate it_)
+* `CO Person`:gear: Preferred Timezone (_This is really a technical thing and not so much a user preference - timezone is typically determined automatically_)
 * `CO Group`:gear: Memberships (for open groups or groups owned by the CO Person) - _we will be talking about Groups in the next lesson._
 * SSH Keys attached to a CO Person record - _we will be talking about authenticators and SSH Keys in a later lesson._
 
@@ -51,7 +51,7 @@ COmanage allows certain attributes (information) to be managed by users directly
 * `CO Person`:gear: EmailAddress
 * `CO Person Role`:gear: TelephoneNumber
 * `CO Person`:gear: Identifier
-* `CO Person`:gear: URL (as of v3.1.0)
+* `CO Person`:gear: URL (as of v3.1.0) (_it's probably safe to omit version numbers and just assume everybody is using the latest version, or whatever version you're training with_)
 
 _By default, these attributes are read only._
 

_episodes/05-firstPerson.md

@@ -28,6 +28,8 @@ Platform Administrators are effectively super users, with the ability to perform
 
 # View the `Org Identity` Object :gear:
 
+_It might make sense to swap the order here. The CO Person is the primary object, and maybe it should be explained first?_
+
 1. Click on the upper right corner of the screen to expand the user menu.
 2. From the menu, select the Organizational Identity shown. This action will open the Organization Identity in "view" mode.