[Draft] MODx 0.9.7+ Terminology Proposal

Quote from: grad at Mar 19, 2007, 09:18 AM

At least concepts and plans for the future releases should be published for the team use in a document form.

I forgot to mention snippets (and other add-ons) in development stage - tvExplorer being a good example. Its documentation in our Wiki would be much more readable and easy to update by anyone (with versioning). Being developed this way it could easily get available to the public when it reaches maturity.

Shouldn’t we aim to move all documentation to the Wiki?

Am I asking too many questions?

Quote from: grad at Mar 19, 2007, 09:18 AM

IMO renaming "Template Variables" to "Content Fields" would help to clarify MODx lingo even further.

I can understand how it would seem to be the way to go, but I am not really sure this is a good idea unless TVs start working differently (I vaguely remember talk about them not being tied to a template anymore). I most definitely agree with you that content fields is a much simpler term : I use it with my clients, they don’t need to understand the concept of TVs.

But someone who builds website with MODx will not benefit from renaming Template Variables to Content Fields. After all, TVs are "just" that, variables which are freely tied to a given template.

I think we should really be clear about distinguishing the end user (or clients) from MODx users who actually build website with the CMF.
Those require two very different kind of communication about what MODx can bring to the table.

I guess that’s one key to selling MODx to end users : translating the technical concepts into user benefits... but technical concepts are technical and it’s best when they describe un-ambiguously the item they describe.

Quote from: grad

I think documents like this one should get published in the Wiki for team internal use. That would allow us to work together on concepts and internal documentation as well as collect information in one place in a structured form. I came on this idea just a few days after joining the team when I tried to catch up with the development discussion, which is spread in a number of topics.

That’s a good point grad and I couldn’t agree more, yet I am not sure it wouldn’t be "resource intensive" to formalize things at this point.
It all depends what you mean there, could you outline the idea a bit more precisely ?

Quote from: grad

After giving it a deeper thought, I think the lack of team documentation is one of the reason for the lack of the public one.

You’re probably right, there.

Quote from: grad

At least concepts and plans for the future releases should be published for the team use in a document form. Remember, we come from different countries, cultures, professional backgrounds, and have diffrent level of English.

Well, so far there has been a few documents published on the team forum, like this one from Jason.
Sure, if we manage to do it, formalizing and synthetizing is a great tool to communicate

What do you mean exactly by document : Word document ?

Quote from: grad

That means not all of us, myself included, are able to understand easily what others try to communicate. Let me quote Ryan:

Quote from: rthrash at Sep 06, 2006, 12:30 AM

The biggest problem with Jason’s stuff is that no one outside of him has really seen it, and quite frankly when he describes it, it seem way too complex and intimidating for me -- I call it too "wooshy".

I remember this line, and it dates back to quite some time.

0.9.7 is alpha tested by the team, which means a nice part of the future code base (for instance xPDO based core) is being tested by the team.
You can hardly say we’ve not "seen" it

I don’t think what you say applies as it did at some early point of the new core development. The past two or three months, Jason has done nothing but making a huge communication effort (the blog post was really nice !), has answered lot of questions from the team (and also coders thanks to the xPDO forums), provided a few guidelines for devs to ensure compatibility with future versions.

Another factor, as you said, is understanding each other (since we’re from different languages and cultures) and I think there was a bit of humor to that quote (which is a bit out of context here too).

Anyway, there will always be room for improvement, but I’d say things have made a lot of progress in this area

Quote from: grad

I’m far from trying to offend Jason. I’m rather trying to communicate a need for a better way of discussing the development path.
What you think?

I am sure you mean well and I share some of your analysis, I think it’s positive to start a discussion about this (to moderator : maybe we should split from grad’s post on ?). We should build upon your impulse to define how we can improve things further

In Jason’s defense, that document is not woohsy to me. Some of the earilier things from last year, yes... but I think I’ve finally beaten him into submission

The wiki would be a good location for the document though and I don’t see any reason not to go ahead and make it public.

Content Fields is the appropriate terminology too. Much more accurate and leaves the flexibility for developers to attach them in any manner they desire via custom managers. This gets back to the framework vs CMS thing. There shouldn’t be any forced content, TV or metadata fields in the future as they simply aren’t used in every case.

Quote from: rthrash at Mar 19, 2007, 10:18 AM

Content Fields is the appropriate terminology too. Much more accurate and leaves the flexibility for developers to attach them in any manner they desire via custom managers.

I take it either you disagree with what I said earlier or else I remember correctly and TVs won’t be tied to templates anymore (?)

Quote from: rthrash

This gets back to the framework vs CMS thing. There shouldn’t be any forced content, TV or metadata fields in the future as they simply aren’t used in every case.

I couldn’t agree more with that, as I said elsewhere (I think sirlancelot brought this up, can’t remember the thread).
I also think we should really make clearer and clearer that "framework" is not in MODx case, a wanna be term as is the case for several CMS but a reality. But that’s a bit off topic

Also on the point of no developer docs, you should see that change with 0.9.7. There will almost be no resemblance to the tools available in previous versions ... so spending a boatload of time there would have been a lot of time wasted. It certainly didn’t negatively hinder project growth!

All great points and areas though, and areas I expect you’ll see tremendous strides in in the coming weeks and months. Your analysis is great and something that I know has driven Jason crazy. You’ll not only information about the solution, but also how to develop for the solution including interacting with our SVN, merging properly to maintain history, etc.

I take it either you disagree with what I said earlier or else I remember correctly and TVs won’t be tied to templates anymore (?)

I think it is tremendously confusing to have things referred to one way with developers and another way with clients. I favor calling anything a client might interact with in client-terminology. If developers can’t get it that "content fields" are tied to tempaltes (or maybe even not!), then they should probably be working with a less-flexible solution.

I’ll have no problem with understanding this, but to me explaining MODx benefits to a client / end user is like explaining the benefits of web standards : I don’t talk about XHTML or CSS, but about separating content and presentation and how it benefits them. It’s a bit like pedagogy, you can’t talk with a layman like you talk with an expert/knowledgeable people.

Now, my reasonning certainly overlooked the fact that some of the lingo will be there in the manager and has to be consistent... good point !

this essentially becomes DocumentVariables (TV’s assigned per document) or what some are calling Custom Content Types (not referring to MIME Content Types)

- DocumentVariables (TV’s assigned per document) ... Yes, Please!

• Cultures (modCulture class)
• new concept to better support localization
• defines granular internationalization settings that can be used throughout the framework
• can define language, locale, currency and date formatting, and anything else that might be culturally specific

This sounds like it will be a huge win for the community...not even mentioning all the other spectacular benefits of the 0.9.7 branch....

Content Fields

Quote from: davidm at Mar 19, 2007, 10:14 AM

someone who builds website with MODx will not benefit from renaming Template Variables to Content Fields. After all, TVs are "just" that, variables which are freely tied to a given template.

I think we should really be clear about distinguishing the end user (or clients) from MODx users who actually build website with the CMF. Those require two very different kind of communication about what MODx can bring to the table.

I disagree with you, David. I share Ryan’s point of view:

Quote from: rthrash at Mar 19, 2007, 10:26 AM

I think it is tremendously confusing to have things referred to one way with developers and another way with clients. I favor calling anything a client might interact with in client-terminology.

Using different names for the same will be confusing to ourselves (and other developers) in the first place. Why to make the life harder? I prefer using descriptive and accurate names, which are familiar to the end-user.

Template variables as we know them, which will no longer be tied to templates, they will become just that - Content Fields. They will hold content, which may vary in format and presentation, but still it will be a content. Also, this is more natural to an average computer user to understand and adopt, as they are familiar with the concept of fields - they use them in their day work.

The proper lingo may probably help you sell the solution to the client. The lingo, which is sophisticated and not natural with no doubt will be a con.

---

Communication (understanding each other)

Quote from: rthrash at Mar 19, 2007, 10:18 AM

In Jason’s defense, that document is not woohsy to me. Some of the earilier things from last year, yes... but I think I’ve finally beaten him into submission

Now, when I re-read my post and your comments, I see I could be more precise. It turned out to be ironic a bit Well, I meant the "it seem way too complex and intimidating for me" part - apart from Ryan and Jason being involved in it. That was exactly what I felt like when trying to catch up with the concepts of 1.0. There were a few reasons, I think - there was no consistent message of the concept; my programming skills are just a fraction of Jason’s and my knowledge of software architecture is limited; finally my English (being a foreign language to me) is less decent than David’s. I felt lost, really.

However, my example shows what we can and will face when it comes to communicate MODx concepts, architecture etc. to the community. For same reasons, I guess. I hope this will give you some background to my way of thinking.

---

Team documentation

I’ll try to explain my idea in more detail. This particular document by Jason is a proposal, and as such it triggers discussion, suggestions etc., which then have to be revised and included (or not) in the document if it is to become some sort of documentation. All that is simply a group work, which can be done not necessarily by the original author. I don’t think we want to formalize the process but would certainly want to involve the team (and later the community). That’s what Wikis are for as they allow collaborate easily and securely (revisioning).

To put it simply, I think Jason should have posted his work in team space in our Wiki (if there is any) to let us comment and modify it - collaborate. The result would be a document (David, this is what I meant by this word) describing MODx lingo. Once it is ready, we could simply publish it to the community. The same pattern should apply to code documentation - I mentioned tvExplorer - as Wiki is the right tool for the task not the forum.

The main advantage of publishing internal docs - be it ideas, proposals, documentation etc. - apart from technical ones (collaboration, revisioning, comments etc.) is that it requires the author to write it well to be understood by others. That means structure it, explain well and use lingo accessible also to non-native English speakers. And in case he/she fails, anyone can correct it.

Quote from: rthrash at Mar 19, 2007, 10:26 AM

Also on the point of no developer docs, you should see that change with 0.9.7. There will almost be no resemblance to the tools available in previous versions ... so spending a boatload of time there would have been a lot of time wasted.

IMO we should go this way with docs the team produces for 0.9.7 and beyond. No one wants to waste the time and effort.

I hope this sound more clear now.

Quote from: grad at Mar 19, 2007, 03:36 PM

To put it simply, I think Jason should have posted his work in team space in our Wiki (if there is any) to let us comment and modify it - collaborate. The result would be a document (David, this is what I meant by this word) describing MODx lingo. Once it is ready, we could simply publish it to the community. The same pattern should apply to code documentation - I mentioned tvExplorer - as Wiki is the right tool for the task not the forum.

Wiki’s don’t provide protected areas. Maybe Collanos is a good solution for this.

Laymen’s vs. Technical Terminology
As with any good human interface, we must provide common terms that illicit clear images of MODx concepts in adopters minds. This interface, much like an API (Application Programming Interface) should be abstracted from the implementation of the application, allowing the implementation to be refactored, optimized, or replaced as appropriate. I believe the same is true of our laymen’s terminology. That’s not to say it doesn’t have a clear relationship to the implementation; in fact, this is even more important, as it will enable and strengthen the ability for the various stakeholders to collaborate on a project using MODx. This is why I have provided laymen’s terms along with technical classes and descriptions associated with the terms. The fact is, end-users often don’t have any technical knowledge or reference to the technical information provided, designers will have a slightly better understanding, and developers will rely on the technical information to guide them to the fulfillment of end-user concepts. But without the technical details, the project IMO, becomes only attractive to end-users. This is the opposite of what I envision, which is to provide a content management framework that enables an infinite number of roles to more easily participate in the lifecycle of the project.

Purpose of the Proposal
I have two goals with this exercise: to drive the simplification of the terminology required of any MODx discussion (i.e. how David talks to clients about web standards) AND to bridge the technical gap between the legacy core and the new object-oriented core for the sake of those contributing to the core, core extensions, or add-ons. I especially want to focus on the concepts related to these terms, see if I left any out (and if so, why), and help the team "light bulb" come on with regards to how these concepts relate to current ones.

For now, this document is the way to collaborate; there is no team space in the Wiki. If you have contributions or revisions, feel free to suggest them directly in the document and post it back, or just note them directly in this thread. I agree we need a better collaborative tool for driving this stuff, but the current reality is we do not have that setup and I need feedback on this now. As we bring 0.9.7 closer to release, I will address the problem of team collaboration in general so it will be much easier to drive future changes...