Discussion: What to call Resources, Graphs, and Resource Instances?

[mradamcox]

I'd like to start this discussion. If there's a better place for it than here, we can move it there.

These are the three entities involved in this discussion, with a short description of how I see them fitting into the larger picture. Resources -- in v3, Resource Types These are the highest level of categorization for records in the database. They have settings and a full graph that defines their contents. Graphs -- no exact v3 analogy, kind of BranchLists... or, generically, "graph components" These are second-tier organizational components, any number of which may be attached to a resource. They have configuration settings similar to a Resource, but must be attached to a Resource to be used. Resource Instances -- in v3, Resources. Database records, I only bring this up because of the ambiguity of using the term Resources as defined above.

To illustrate the Resource = 1st-tier and Graph = 2nd-tier concept, I've made this diagram, drawing from how I now understand these pieces to be interacting from a UI point of view:

One takeaway is that while we create a Graph by connecting a bunch of nodes, it is may be more commonly seen and dealt with not as a set of nodes (i.e. the graph view), but as the resulting Card. This could pull us away from using the term Graph toward something more generic, like Component, Element, or Part.

Other thoughts regarding the current terminology:

1. Users will intuitively want to refer to Resource Instances simply as "resources", as in "Here is a database of all our cultural resources". With the current terminology, there is no clean way to rectify this with the fact that Arches currently considers Resources as "categories of database records". An illustration of this ambiguity is the "Add New Resource" option on the left-hand menu.
2. I know that underneath there is actually very little difference between Resources and Graphs, but after seeing the workflows that Dennis imagines as typical of user's experience, I think the UI should emphasize their differences, not their similarities. There are many other way this can be done (only showing certain edit menus for each one, etc.), but terminology should support it as well.
3. Along these lines, Graphs only actually function as components of something larger (they are always "underneath" a Resource's top node) but the word Graph does not illustrate this second-tier nature clearly enough, especially because a Resource will have its own graph, which is fundamentally different from those that compose it.

Brainstorming: Resource Types, Graph Branches (or just Branches), Resources is very literal and straight-forward Resource Categories, Category Elements, Resources is more general Resource Types, Components, Resources

Resources, Elements, Records to continue using Resource like this, we should consider using Record for Resource Instance

or, more abstract ideas... Comprisers, Composers, Resources Resource Trees, Branches (or Limbs), Resources

Anyway, I just wanted to start this off with some of my thoughts on the matter, based on my current understanding of the system.

[dwuthrich]

I agree that its a good time to get our terminology in order. I like the Resource Types/Components/Resources suggestion because its pretty generic. The "Components" and "Resources" (as applied to an instance) seem particularly straightforward. I wouldn't have too much trouble ditching "Resource Types" for something even more generic if there's a simpler term that others like.

[robgaston]

I would like to put a vote in for Graphs (for what we now call "Resources"), Branches (for what we now call "Graphs") and Resources (for what we now call "Resource instances").

The terms "Graph" and "Resource" are already in use w/in the community these days, I think, and are used as described above, therefore adopting these terms might reduce mental overhead in switching to Arches 4. The new concept we are adding (as @mradamcox points out) is the second tier partial graphs which we have been calling "Graphs". This concept has come to fit a concept we used to describe as "Branches", which I think was a pretty descriptive term (as it implies it's partial nature).

I also think it would be nice to have simple one word names for each of these things, but that's not necessarily high value.

[adamlodge]

Rob et all,

Unfortunately, I don’t like the use of the term “graph" to describe anything specific to Arches. Graphs (or “Graphing”) is more a data structuring methodology that we employ in many portions of Arches - including resource type schema, business/resource data, and concept/rdm data. My opinion is that we are well advised to not use the that term to describe anything approaching a business object in Arches.

Given the value of staying consistent with existing legacy terminology, my vote is for: resource types, resource properties (i know its a new idea, but the word “properties” is a common stand-in for field names in logical data models), and resources.

Most importantly, I think that it is imperative that we STOP calling using the term “resources” when what we are talking about is the schemas that store resource data. That is just asking for confusion and trouble.

---

Adam Lodge Farallon Geographics

Geospatial Systems Consultant

On Sep 16, 2016, at 10:05 AM, Rob Gaston notifications@github.com wrote:

I would like to put a vote in for Graphs (for what we now call "Resources"), Branches (for what we now call "Graphs") and Resources (for what we now call "Resource instances").

The terms "Graph" and "Resource" are already in use w/in the community these days, I think, and are used as described above, therefore adopting these terms might reduce mental overhead in switching to Arches 4. The new concept we are adding (as @mradamcox https://github.com/mradamcox points out) is the second tier partial graphs which we have been calling "Graphs". This concept has come to fit a concept we used to describe as "Branches", which I think was a pretty descriptive term (as it implies it's partial nature).

I also think it would be nice to have simple one word names for each of these things, but that's not necessarily high value.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/archesproject/arches/issues/821#issuecomment-247654064, or mute the thread https://github.com/notifications/unsubscribe-auth/AJPDaxD_FMky76ZJL_jhcNHkbRHdueK1ks5qqsxNgaJpZM4J-a4m.

[robgaston]

To your point, @adamlodge, about not using the term "resources' when referring to schema: I think there is value in not naming all of these things "resource {something}", as our goal here is clarity in the minds of end users and I think that naming is part of what muddles things and leads to imprecise use of words like "resource".

I think, ideally we'd only use the word "resource" when talking about resource instances (not types or branches), but obviously the terms "graph", "class", "type", "property" and"component" on their own are all overloaded. Perhaps the term "Classifications" instead of "Graphs" could work. I think "Properties" (on top of being overloaded) is a bit insufficient, as we are actually talking about entire collections of nodes and their structure. I keep coming back to "Branches" for that one.

[mradamcox]

To @adamlodge 's idea of "properties", I agree with what @robgaston says, "property" seems more appropriate for something simple like a setting (inactive vs. active), rather than a whole network of settings, nodes, and configurations, which is what the "Graphs", as they are currently called, represent.

I'm liking Classifications, Branches, and Resources.

Classification, even though it's not as strong as Category, is clear enough to denote a top-level division. One problem though, the concept of "reclassifying" something would not make sense at all in an Arches database, but using that word may imply that it should.

Branch (and Component) both have the right implication of being part of a whole, but Branch more clearly describes what is actually going on, and I like the visual that comes with it.

For what it's worth, I like testing these by using the words in sentences. "There are 5 classifications in our database" (more correct to say "resource classifications"?). "Each Classification consists of one or more Branches." "What classification of resource do you want to add?" etc...

[adamlodge]

How does "classes" rather than "classifications" strike y'all?

On Sep 16, 2016 12:04 PM, "mradamcox" notifications@github.com wrote:

To @adamlodge https://github.com/adamlodge 's idea of "properties", I agree with what @robgaston https://github.com/robgaston says, "property" seems more appropriate for something simple like a setting (inactive vs. active), rather than a whole network of settings, nodes, and configurations, which is what the "Graphs", as they are currently called, represent.

I'm liking Classifications, Branches, and Resources.

Classification, even though it's not as strong as Category, is clear enough to denote a top-level division. One problem though, the concept of "reclassifying" something would not make sense at all in an Arches database, but using that word may imply that it should.

Branch (and Component) both have the right implication of being part of a whole, but Branch more clearly describes what is actually going on, and I like the visual that comes with it.

For what it's worth, I like testing these by using the words in sentences. "There are 5 classifications in our database" (more correct to say "resource classifications"?). "Each Classification consists of one or more Branches." "What classification of resource do you want to add?" etc...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/archesproject/arches/issues/821#issuecomment-247681451, or mute the thread https://github.com/notifications/unsubscribe-auth/AJPDa_5i5LjvErOimkP6S2lwU7kR4vc6ks5qqugmgaJpZM4J-a4m .

[robgaston]

"classes" strikes me as bad, because "class" is usually a reserved word in most languages.

[robgaston]

Also, I think the word "class" as a label for things in the UI could be ambiguous to many users, whereas "classification" seems a bit clearer.

[apeters]

I think Branch and Resource are clear and meaningful, but _Classification_ seems totally ambiguous to me.

I would humbly suggest Resource Graph as the term to describe the collection of nodes (scheme if you will) that defines a Resource (Instance).

As in.... "to create a Resource Graph, select the Branches from the Branch Library that you want to include in the Resource Graph".

The reason I think Resource Graph is meaningful is because it implies the Graph that underlies a Resource (which people see as the instance itself). I append the term Graph to Resource to back up what the user sees in the UI itself. As an alternative, Resource Model could be used if "Graph" is deemed unacceptable.

[apeters]

We had a discussion during our Monday morning meeting about this and the upshot was that there seems to be some momentum around the term Resource Model to denote the collection of nodes and edges that define a resource schema.

We all agreed that Branch and Resource are clear and meaningful for what are now called "Graphs" and "Resource Instances", respectively.

[mradamcox]

Solid work. I was leaning that way after Alexei's last comment. I think it makes good sense to go with Resource Model, Branch, and Resource. I began using those terms in some documentation yesterday, and it was working out well.

On Tue, Sep 20, 2016 at 11:03 AM, Alexei Peters notifications@github.com wrote:

We had a discussion during our Monday morning meeting about this and the upshot was that there seems to be some momentum around the term Resource Model to denote the collection of nodes and edges that define a resource schema.

We all agreed that Branch and Resource are clear and meaningful for what are now called "Graphs" and "Resource Instances", respectively.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/archesproject/arches/issues/821#issuecomment-248365319, or mute the thread https://github.com/notifications/unsubscribe-auth/AJ8bhAfYlGoa_luUqRckKLFNCn0MwqUlks5qsBHrgaJpZM4J-a4m .