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, itseems like defining a group (for all users?) happens with only aspecific 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 auserId? If its required, because we're associating the group with a user, thenwhy 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