New Revo tabs and terminology

Since we no longer show the terms "Content Elements" and "Web Resources" in the Manager, I wonder if we should do away with those phrases and just use "Elements" and "Resources" in all (or almost all) of the documentation.

The longer phrases are certainly defensible, but I’ve always thought they were somewhat confusing and I find it awkward to switch back and forth in documentation (e.g. "click on the Elements tab which shows the Content Elements tree).

Thoughts?

I am not sure this is confusing as long as it’s consistent and adds meaning to "Elements" and "Resources" which are a bit conceptual to begin with. If you do remove those additional words then it would be nice to have a bubble tip or a link to refer to the definition of the term everywhere in the documentation. You can never be too explicit with documentation IMHO, as long as you remain concise enough to avoid confusing readers.

I’m always for the shortest version possible that still is clear. As long as there’s a glossary (or a tooltip, great idea David!) then I’m ok with the short version for sure.

The biggest source of confusion, IMO, is that one would think that "content fields" would be closely related to "content elements." When we’re talking about content fields, though, we’re usually talking about resources not elements and it seems likely that that would make a newbie’s head spin all the way around.

Quote from: BobRay at Sep 12, 2009, 05:41 PM

The biggest source of confusion, IMO, is that one would think that "content fields" would be closely related to "content elements." When we’re talking about content fields, though, we’re usually talking about resources not elements and it seems likely that that would make a newbie’s head spin all the way around.

What was decided to be called Content Fields is wrong IMO; it is really Resource metadata or Resource Tags, and when the "content" field itself is gone from the Resource table (and becomes a Content Element as it should be), this will be much more obvious. This is further confused by having Content Element tags from TV’s merged with Resource metadata tags. I don’t think we should worry so much about what these are called though; the important thing is identifying Web Resource objects from Content Element objects from the templating or Content Tags that cross all the boundaries and provide a way for designers to access these things when constructing their sites. There is simply to much complexity in how this stuff works together to simplify it as much as we would like, so let’s not take it too far and stick with Resources, Elements, and Tags for short. The complexity can be described/clarified in the documentation for those that care.

Quote from: OpenGeek at Sep 12, 2009, 07:30 PM

What was decided to be called Content Fields is wrong IMO; it is really Resource metadata or Resource Tags, and when the "content" field itself is gone from the Resource table (and becomes a Content Element as it should be), this will be much more obvious. This is further confused by having Content Element tags from TV’s merged with Resource metadata tags. I don’t think we should worry so much about what these are called though; the important thing is identifying Web Resource objects from Content Element objects from the templating or Content Tags that cross all the boundaries and provide a way for designers to access these things when constructing their sites. There is simply to much complexity in how this stuff works together to simplify it as much as we would like, so let’s not take it too far and stick with Resources, Elements, and Tags for short. The complexity can be described/clarified in the documentation for those that care.

I think I see the issues, but I’m not sure I see a good way out. We have to call everything *something* and do so consistently. The [[*something]] tags definitely need a single name and it will appear often in documentation.

It’s helpful, from a documentation standpoint, that content fields be displayed with content tags. Saying that Resource Metadata and Template Variables are displayed with "content tags" doesn’t work very well, IMO. I really don’t like "resource metadata" anyway for a variety of reasons, the main one being that it’s a pain to type.

Calling them "resource tags" I could maybe live with, but they’ve been called "content tags" for a while now in various locations.

Hmmm. . . How about "Resource fields" and "Resource tags"? It’s not much of a stretch to consider TVs to be resource fields. They’re fields in the Resource editing section of the Manager. So referencing TVs with a "resource tag" makes some sense and the other "resource fields" are literal fields of a resource.

We definitely need to settle this ASAP, though - IMO.

Let’s back up a little, Content Tags originally referred to all the Tags in MODx that were not represented by a Content Element (this is reflected in the actual code), though I ambiguously referred to all Tags as Content Tags (confusing I know) at http://modxcms.com/develop/roadmap.html. I’d agree we should refer to the Tags that output the processed content from Template Variables and Resource fields (fields of the Resource object) as Resource Tags. When we talk about all MODx Tags, we can refer to them simply as Tags (or possibly Output Tags since they are used to output things) to clarify the previous ambiguity.

Agreed? I’ll be glad to update the roadmap and glossary with these clarifications...

Quote from: OpenGeek at Sep 13, 2009, 04:14 AM

Let’s back up a little, Content Tags originally referred to all the Tags in MODx that were not represented by a Content Element (this is reflected in the actual code), though I ambiguously referred to all Tags as Content Tags (confusing I know) at http://modxcms.com/develop/roadmap.html. I’d agree we should refer to the Tags that output the processed content from Template Variables and Resource fields (fields of the Resource object) as Resource Tags. When we talk about all MODx Tags, we can refer to them simply as Tags (or possibly Output Tags since they are used to output things) to clarify the previous ambiguity.

Agreed? I’ll be glad to update the roadmap and glossary with these clarifications...

I think we’re on the same page. My main concern was that each tag with a particular token (or no token) have a specific name. So after our earler discussions, I did this: http://bobsguides.com/revolution-tags.html.

If I’m understanding you, the only changes now would be:

content tags -> resource tags
content fields -> resource fields

I’d prefer to refer to tags in general as "MODx tags" or just "tags" for short. I don’t like calling them "Output Tags" because they’re not always playing that role (e.g., when used in snippet parameters).

On the elements and resources, I think I’d maybe say once or twice that "resources" is short for "web resources" and "elements" is short for "content elements" and just call them resources and elements everywhere else. I have about 500 MS pages where I’ve called them consistently by their long names so I have some editing to do. Search and Replace won’t do it because something like "expand the content elements part of the tree" has to become something like "click on the elements tab."

Let me know if we’re settled here and I’ll redo Bob’s Guides and start editing the book.

Quote from: BobRay at Sep 13, 2009, 07:00 AM

If I’m understanding you, the only changes now would be:

content tags -> resource tags
content fields -> resource fields

That’ll work for me...

Quote from: BobRay at Sep 13, 2009, 07:00 AM

I’d prefer to refer to tags in general as "MODx tags" or just "tags" for short. I don’t like calling them "Output Tags" because they’re not always playing that role (e.g., when used in snippet parameters).

They are actually always returning a string output, so I would challenge that, even used in snippet paramaters.

Quote from: BobRay at Sep 13, 2009, 07:00 AM

Let me know if we’re settled here and I’ll redo Bob’s Guides and start editing the book.

Go for it.

Good. Bob’s Guides is (hopefully) done. Now for the book (sigh).

BTW, I did the Revo Glossary page and one other page (can’t remember which one) at modxcms.com.