Description
What article on segment.com/docs is affected?
Spec: Groups
What part(s) of the article would you like to see updated?
So, it seems like the Groups API is, effectively, a way to set a many-to-many relationship between users and groups objects. (Maybe??)
However, it seems like defining a group (for all users?) happens with only a specific association between a user and a group, including setting the name and the traits of the group?
It says that Groups have unique identifiers, so why then, does defining a group require a userId? If its required, because we're associating the group with a user, then why are we defining the name and the traits of the group? If groups are not account-wide (objects for all users), and are basically a sub-object of a given user, then how does this square with a group representing a "company, organization, account, project, or team"?
I cannot overemphasize how confusing either this API is, or the lack of clarity in the documentation is. If groups are just an arbitrary set of user-owned objects, then... I don't know, maybe don't call them "groups" (since groups encompass multiple users, by definition)? Or define that more clearly? If groups are account-wide, then please add to the documentation what the name and traits are doing there.
So, in this case, it's not so much that the documentation doesn't say how to use this API—it does—it just has a complete lack of clarity for how using this API actually functions.
Additional information
No response