The Help! in Revolution is no help.

Is it just me, or does anyone else find that the Help! in Revolution is gobbledegook? I can hardly understand any of it. I have tried to use it several times when stuck on something, and virtually everytime I have just thought, "What on earth are they talking about?".

I admit that I am new to MODx and to CMS’s, but surely, am I not the very sort of person that Help! should be designed for? It’s just total geekspeak. And it’s also very badly put together. Isn’t there anyone in the development team who can write good, plain English?

For a start, I have to say that I find all the strange, MODx-only terms very offputting: "Resources", "Chunks", "Snippets", "Contexts", "Plug-ins". What are they?

For "Resources", Help! says, "A resource is a representation of a page in MODx." Then, why not call it a Page? Or Document, or File, or something else familiar? Why invent something different and confusing? And what is all that about Weblinks and Symlinks and Static Resources? Never use them. Never heard of them. A minefield of confusion.

As another example, when you want to find out what a Context is, Help! says, "Contexts allow MODx configuration settings to be overridden, extended, isolated, or shared across domains, sub-domains, sub-sites, multi-sites, cultural-specific sections, specific web applications, etc."

Very helpful. Now all I need to do is find out what MODx Configuration Settings are and why they need to be overridden, extended, isolated, or shared across domains, sub-domains, sub-sites, multi-sites, cultural-specific sections, specific web applications, etc. Then I’ll know what Contexts are.

Except that there is no heading for "MODx Configuration Settings", or even "Configuration Settings". (Try putting either in Search and you’ll see what I’m up against.)

Then there’s a sub-heading of Contexts called "Using One Gateway Plugin to Manage Multiple Domains". What is a gateway? What is a gateway plugin? No definition. No explanation. On reading further it only gets worse and worse.

On top of everything, the whole structure of Help! is diabolical. When you’ve finally got through the nightmare of installation (don’t kid anyone that it’s easy: it took me four days to negotiate all the pitfalls), you think, "OK. What now?"

So you look in Help!. The first heading is Getting Started. That sounds good. Click. Huh, a list of subheadings. First one: Server Requirements. But I’ve already been through that in the install. Next: Installation. Installation?! I wouldn’t be here in Help! if everything wasn’t already installed! I want to find out how to use MODx to build a website!

Next heading: An Overview of MODx. Maybe that’ll help me. "MODx is a Content Application Platform. What does this mean? Well, that depends on who you are: ...bla bla bla bla (seven paragraphs)...". No that’s not it.

Next heading: Making sites with MODx. Aha. Click. Oh dear! A long list of subheadings and subsubheadings and subsubsubheadings. OK, first subsubsubheading: Resources. Oh my God! A long list of subsubsubsubheadings and subsubsubsubsubheadings.

Plough on steadfastly with the first subsubsubsubheading: What is a Resource? "A resource is a representation of a page in MODx. There are different types of Resources, such as documents, weblinks, symlinks, actual files, or many other things. The default Resource type is a Document, and simply represents a webpage on your site.There are 4 total types of Resources, and they are Documents, Weblinks, Symlinks, and Static Resources."

But you just said they could also be "actual files" and "many other things". What happened to them? And what on earth could all those "many other things" be anyway?

And so the confusion begins...

If I’m having this sort of trouble, think of my poor clients! I know I should listen to that little voice at the back of my head that keeps saying "You should have downloaded CMSMadeSimple", but I just can’t face another install right now. Maybe tomorrow...

I think there’s a -although small- element of truth in your rant. However, when you embark on mastering a new open source(!) CMS, you know in advance that there will be a learning curve. The steepness depends on the product and your skill set. So you should be prepared to soak up new things and learn the "local speak", so to say. Chunks and snippets might be specific MODx dialect but I’ve seen them used in other environments as well. I agree to a certain level with you that the documentation is in some areas "geeky".... it is very much work in progress and is being improved constantly.

If you’re not prepared to compromise, buy one commercially or get one that better suits your needs which mean you probably will be shielded from the typical powerful features that MODx offers.

Last thing: MODx install is a breeze. Four days??? Did you try getting help via the forums?

Thanks for your reply skndn60.

I think there’s nothing wrong with inventing a new word for a particular concept if there isn’t a suitable one already available. If this is the case then the new word should be clearly defined and explained in a way that everyone can understand. That, surely, is a basic rule of communication.

Regarding the install: yes, I had to search the forums and the web for solutions to the difficulties, and that showed me that lots of people have had problems. It took so long because I had to wade through all the problem posts to find ones that were identical to mine and had replies that gave solutions that worked. I’m sure it can be a breeze if you are lucky with your set-up, but not everyone is.

Welcome to MODX.

I hear what you say.

I started with evo.

I used various tutorials.http://codingpad.maryspad.com/beginner-tutorials/
http://bobsguides.com/MODx.html
http://sottwell.com/

Hope you find some help in these links.

It may seem hard at first but a local developement server is the best place to start IMHO.

aspen, I found your piece hilarious and, for the most part, right on the money. The only exception is related to the MODx terms. I took your view on them at first, but after you understand them, you realize that not only do the names make sense, but that there are no better alternatives for any of them. In almost every case I’ve wrestled with, the alternatives would be worse (and often quite misleading).

A resource, for example, is really (at least for now) a row in the MODx site_content table, but saying that wouldn’t help anyone. It isn’t a file or a web page (until you render it somehow) -- it’s an abstraction and to some extent it defies simple explanation."Resource," BTW is a standard web term that’s been around for over 20 years.: http://en.wikipedia.org/wiki/Resource_%28Web%29

That said, absolutely all help systems are horrible at first. In the early days of MS office, I used to end up screaming obscenities at the Word help system every single time I tried to use it.

Help systems are written by programmers since, especially at first, they are the only ones who know the system (or how to create help entries). The programmers *always* make two completely innocent mistakes:

1. They skip over details that are so familiar to them that they don’t even know they exist any more, like the fact that a snippet tag needs a question mark if it has parameters or the fact that there are people who don’t know what a System Setting is.

2. They tell you what a menu choice does, but not why you’d want to do that, or when.

They’re literally incapable of seeing the system from your perspective. That’s why it’s critical that people like you speak up. We don’t always get this kind of feedback because most people are too afraid of seeming dumb to speak up at first -- and once they understand everything, it’s too late. It’s a bonus when the feedback is so entertaining.

One of the biggest issues is that in order to be as powerful as it is, MODx is necessarily complex, with lots of moving parts. MODx is more like a toolbox than a tailored CMS solution. Or, if it helps, more like a lego set than a toy house Because of that, it’s impossible to give a simple answer to the question, "How does this thing work?". I can explain WordPress to an eight-year-old. I mean no offense to WP, it’s just a simpler entity. See the site in my sig. for a low-level attempt at explaining MODx. Here’s an explanation at a deeper level: http://bobsguides.com/revolution-objects.html. There’s a glossary of MODx Revolution terms here: http://rtfm.modx.com/display/revolution/Glossary+of+Revolution+Terms. Feel free to suggest specific improvements to either (or anything else you feel needs clarification).

Let me close with another point. MODx is an amazing but understaffed Open Source project that you got for free. I don’t mean that as an excuse, but try to remember this fact: The only people who know enough to develop the help system you need are busy creating, fixing bugs in, and improving the MODx engine and UI. In Open Source projects, the help and documentation *always* lags behind the product. It’s a fact of life. The same thing is true of commercial products, the lag is just less pronounced.

Although you may take some heat from MODx fans, contributions like yours are immensely helpful (especially if you continue to provide them and, once you understand things, offer specific suggestions for improving the help system or the documentation). You mentioned having someone who could write well provide explanations. Check the mirror.

Thanks for the feedback and a good laugh.

Bob is right on... it sounds foreign when you start but
then it all clicks and you talk the "language" perfectly.

I started with Evo and now I am in Revo and I am having
some of the same witht he new features but I am working
them out.

I started www.modxperience.com to help people move along the
curve faster, check it out. It starts way at the beginning,
on how to get a domain name, but it moves towards making a
website in a few tutorials...

Aspen, that is an excellent post!

I have sort of railed against some of the issues you raise.

But here goes: you have to endure some pain no matter which CMS you choose. The frustration will come in many forms, but its unavoidable really. The really simple systems will be very limiting in what you can do. The large feature rich plug-and-play systems can produce too many overwhelming choices and doing anything custom is going to be very frustrating. I tried about ten systems before I settled on MODx.

MODx is not for everyone. Deploying MODx means you have tons of flexibility to do many things your own way. And there are many ways of doing the same thing in MODx.

Knowing some PHP is very helpful but not essential. You should know how to create and manipulate HTML markup and work with CSS though. I still find it very useful to first build my HOME page and basic site system using static markup (that validates) and CSS. From there you have to spend some time learning the core MODx placeholders and main snippet functions that will make your content and navigation function dynamically from within MODx.

Learning this stuff is like math: you can’t jump into advanced integral calculus without knowing algebra. Some study is required.

Even if you intend on using and learning the Revolution branch of MODx I would first study the existing Evo material. There is more of it and its better explained in my book.

Two of the best sources for getting your feet wet are these two great sites:

http://codingpad.maryspad.com/2009/03/28/building-a-website-with-modx-for-newbies-part-1-introduction/ and http://www.sottwell.com/

Mary at Codingpad probably does the best job of using english to carefully build an understanding of MODx. Be sure to use the guest login on Susan’s site (http://www.sottwell.com/) to see how all the pieces of her site fit together. There are many other resources but I would start with these two first.

But you do raise some great points. I have 800 posts here and am far from being a MODx newbie but I still find some detailed threads to include language so vague, obtuse and full of user assumptions that I have no idea what people are talking about. Building incredible widgets takes expert knowledge and experience. Communicating the features of what that widget actually does, why you want it, how to deploy it, how to customize it, etc, etc also takes a lot of expert knowledge and experience. Being able to communicate these facets effectively is vital to others. Some of these pieces can be delivered with nothing more than brief geekspeek and assumed knowledge from the end user.

I would be sure to create a local testing ground (WAMP, MAMP, etc) and add as many test installs of MODx as you like. Learn the key phrases and placeholders and explore the backend Manager carefully. Do not expect all this will happen instantly. It won’t. But with a little time invested you will begin to click with the system. Odds are you will have periods of exhilarating "aha!" moments along with flashes of new frustration.

But, I urge you to stick with it. MODx is totally worth the study...

Hope this helps!

Max

Thanks for all your very good replies, allanb, BobRay, charliez, and Photowebmax. Sorry if my post may have sounded like a rant against MODx as a CMS. That’s not the case, because, until I can fathom how to use it, I’ve no idea how good it is. My frustration is purely with the way MODx is presented to me, as a newcomer, and anyone else I may introduce it to, such as clients.

Although I may be new to MODx and CMS’s in general, I’m not exactly a dummy: I have a degree in computer science and mathematics and I have recently qualified as a web designer. Yet every time I go to the Help! in the MODx console, it makes me want to tear my hair out; and I think, if I feel like this, how am I ever going to be able to get a client to use this interface? After all, when they are not sure about something, their first port of call is going to be the Help! link.

On top of that is the other problem that I mentioned: the MODx terms, like Resources, for example. To a normal person, a resource is something to fall back on when you need help with the job in hand. For instance, to a web designer this might be Photoshop, or information on the web, or a PHP reference book, or whatever. In the context of a CMS this could be the add-on packages, or the Help files, or the forum community, or a book on Modx. It certainly wouldn’t be the web pages themselves or their abstract representation.

If a client asks, "Why are they called Resources?", I guess I’ll have to say, "I’m not really sure, but if you want to know, there’s an obscure, complicated and confusing article all about it in Wikipedia, entitled Resources(web), but only a few people in the world have ever read it."

If a client asks, "Why are they called Resources?"

http://www.thefreedictionary.com/_/search.aspx?SearchBy=0&TFDBy=0&Word=Resource%20(Web)&tab=16

A Resource is the "R" in URL (Universal Resource Location)—as in anything you can put in your browser address bar and to which you can navigate. In MODX Revolution, it can be a web page, a file, a RSS feed, a RESTful web service or... it’s much more than just web pages.

I’m very much into not using jargon if at all possible, but in this case, proper terminology really does help the overall understanding of things.

What would you suggest calling a Resource?

As an aside, I’d also be interested in your thoughts on http://dev.modx.com/learn/quickstart/ Would that have helped your initial learning curve?