A "simpler" approach for webdesigners

I really enjoy ModX and are migrating some clients from wordpress and joomla to modx.
BUT I’m a webdesigner, and not a programmer, even if I understand and can modify a bit of php, often I don’t understand the more esoteric uses of some parameters, or functions.
And this gets me to be often stuck on making something even simple: for example, last time I tryed to use getresources to display news from different areas in different parts of my homepage, with no result. When I asked for help I got a very tecnical response wich I could not fully understood (change some parameteres that I don’t even understood). Then, trying and retrying I got to use GetPage insteade of GetResource, and BANG, the site is functioning.

Ok, as I already admitted, I’m not a programmer, and the more technically minded in this forum probably will laugh at my problems.
BUT I think ModX could really become more popular and used, and beat the hell out of every other CMS, if it would simplify it’s adoption by independent webdesigners, wich often don’t even know a bit of PHP or programming.

I think there are 3 ways to do this, and they have nothing to do to "prepacked content" or "templates".
The first would be to ship modx with some basic packages (wayfinder, getpage, tinymce) like it was in evo. I read that this is already in the roadmap (custom installations) if I’ve understood well, and that would be good, since I loose much time in browsing the package manager every time I make a new install of modx, while in Evo I had all prepacked.

The second would be to ship some CHUNKS that would enable the user to make simple things, like 3-4 wayfinder "call chunk" (or snippet) for first level menus, second level, etc. THEN, give the user NOT a "sample site", but a location (maybe in the tabs, like it would have be done in a webdesigning software) in where to find a "calls repository".
That would be something like a list of calls named in a SIMPLE way (like Horizontal first level menu) and with a bit of explanation. The designer would then click that or copy and past in the template, and so even someone who never understands ANYTHING in modx, could create a site.
Think of the placeholders for example: we who work daily with Modx know them, searched them in the wiki and so on. But if we had them clearly inside a "placeholders" tab or button in modx, we would have saved HOURS of time of learning, wich could have been spent on the more difficult tasks. And new users so would find it less difficult and more inviting.
Even in my daily work, I’ve created a set of "examples" for myself to let me know how to do THIS and that. That speedes up my work, and let me remember how modx works.
I don’t think it needs much to introduce this in modx, but would really do MUCH for the usability of it (and I think even the more "tech" people would enjoy that).

The third thing, would be to make the "examples" in the guides, wiki, and so on, more clear. And to make MORE.
People like myself (and most others, even if they wouldn’t admit ), when approach a new programming language, like to copy and past a string of code, and modify it to their needs, and learn trough this process how the software works.
Often the examples have wrong parameters, or refer to "chunks" and "placeholders" without making an example of how those would be created.
I’ve read the wayfinder guide someone has done on the forum. And I got stuck in places (even knowing wayfinder pretty decently) because the examples were very caothic.

The examples must be more like: I use this call XXXXXX to make this: and explain How it works.
Instead of: if you want to do this in modx, wich uses this and that for doing that, u can use a call like this XXXXXX (usually a non working call), while modifying the parameters X and Y (usually without a very deep explanation of what those parameters do), and putting that in a chunk (without a working example).
Probably it would have been also FASTER to make more working BUT less articulated examples.

One good example of examples WAS (since it has changed and I cannot find them, but maybe I never searched well) the muddydogpaws examples of wayfinder. I learned more "operationally" from those than from the forums and wikis.


Sorry for the long post, I don’t have talent for synthesis

Erebus/Gio

Ah, if I’ve not enough clear, premaked templates and websites are NOT the right choice for me.
Because when I approach Modx, I have a free approach, and I create my website first in css xhtml, and THEN make it dynamic, and since this is the modx philosophy, at least from what I understood when I was attracted to it, I think is what most modx user do.
So I want "PARTS" for MY website, and NOT an entire premade website, maybe done in a different way from what I’m used, wich I have to modify and change and then call for the Gods aid when nothing works as I intended
Surely I CAN copy and past parts from THAT website, but since it has not ALL the parts I need, in the end it’s simpler to start with a blank site, but have all the parts I need in a convenient way.

You’re the kind of people we need to help improve the documentation.


Really.


Please, do keep notepad open when you’re browsing around and take notes and links of what is unclear, and what is not working. Then post these somewhere (eg the documentations section).

I don’t mind spending time to improve the documentation (with more/working examples).. but since I’ve used this system for ages, I’m stuck in the modx terminology and I don’t see the unclarities. Having people who do not have this knowledge pointing out specific things to change would really help us help you.


That said, I think your points are quite valid, even if I do think differently...

1) While it would be a good idea for startups, it also limits the freedom to do whatever you want. If you don’t want to use TinyMCE (and I do know quite some people that don’t) you’ll have it installed anyway. I think a better solution would be to provide Packages which consist of other packages. Like a Blog package (which ships getResources, Archivist, tagLister, Quip etc) and a Site package (getResources, Wayfinder, getPage). Installing one big package would save you the time to navigate the package manager endlessly.

2) I’d rather have that in the Documentation then in MODx.. it would add in a lot of stuff the slightly more experienced user would never use. There’s a "Help" button on the top right corner of every (I think) page, which links to the RTFM. Perhaps those landing pages need to be improved. (Although at a first glance, the landing page for resources looks pretty decent)

3) Agreed.

Some great points. The documentation (especially the API docs) desperately needs examples. Unfortunately, most of the people who could write them not only don’t need them, they have no time to create them because they’re busy developing MODx and/or earning a living. My book will help some (hopefully) when it’s finally available.

I do like the idea of a placeholder cheat sheet. It wouldn’t be that hard. In fact, my book has an example that creates a custom Manager Page with a multipage cheat sheet containing MODx system settings and MODx tags. A good third page would be common placeholders.

A cheatsheet that let you insert placeholders with a click would be even better, although once you know them, you’d probably never use it.

If you look near the bottom of this page, the first section of the Common Objects and Some of Their Properties part lists all the placeholders available in a MODx resource (document): http://bobsguides.com/revolution-objects.html

Yes, I strongly agree with all of that both -- with the Erebus74’s words on the need for more docs, and with Mark H.’s observation that problem that the experts are already busy and anyway, it’s not what they’re good at! Comments on the problem first, what I’m doing about it after.

THE PROBLEM

Documentation desperately needs examples. I’m an academic, and the psychology of programming was my area. There is overwhelming evidence that novices rely heavily on working examples at the beginning, both for analysis to see how they work and for creating programs by successively modifying examples.

An example of not enough doc, so you can see where difficulties arise: I have now spent over 2 hours trying to make getResources sort its results. I am puzzled because the documentation for getResources says I should use sortBy and sortDir, but those were deprecated in Evo’s Ditto 2.1 in favour of orderBY. I got Ditto working in Evo but am stuck in Revo. The getResources doc has little to say - it does have some examples (full credits for those!) but a few more would really help, so that I can see whether I’ve hit a bug or whether it’s my finger trouble.

Another issue is the problem of searching the existing documentation. I would like to be able to find stuff faster, with fewer page visits to break my concentration. I would appreciate a search box that allowed ’any word’ or ’exact phrase’, and I would like a MUCH more condensed page template so that lots more text fitted on one page.

WHAT I’M DOING ABOUT IT:

I’m a MODx novice, so I can understand the difficulties; and I’m an experienced writer and hope I’m a clear one. So I think I should try to contribute by creating examples, so far as I’ able.

(1) I’m building a little site to show some simple bits of MODx in action. Then I’m going to publish documentation for the site, showing how it fits together - how the parameter passing works, how the Wayfinder and getResources calls work on each page, and so on. It will be a very simple site indeed (the half-finished version is here: http://tgsketches.me.uk/~tgsketch/petclub/ ).

(2) I have a nearly-finished doc about Ditto in Evo, which is designed for novices. You can download the current version here: http://tgsketches.me.uk/~tgsketch/MODxNotes/DittoNotes_Evo.pdf (it’s currently 35 pages of pdf but it’s full of examples). If anyone takes the time to read it and has comments/corrections please send to [email protected]

(3) I’m collecting the documentation that comes with each snippet I investigate and I intend to make a little lookup website where visitors can quickly access the documentation that comes with snippet X. If I add commenting features, it will be possible to leave guidance for future visitors. Haven’t started yet - is it a good idea?

Last remark: I’m enjoying MODx, except for the problems I mention, and I think it’s going to be extremely useful. Thank you everyone. Keep up the good work.

I get your point on "complete packages", and when they will be there they will simplify one of the points I was asking for: removing the need to do every time a fresh install, then browse the packages (even if I know what packages I need, I don’t ever remember where they are and I spent every time much time on that simple task). While a complete package or two could do the trick.

For the cheatsheet/examples, I would like to lend an hand, but I feel I’m too inexpert (as I said, I’m not a programmer and still feel a newbie at Modx, even if I’m learning every day more), and I don’t want to make an example and to find I have used a "deprecated" or bad way to use that snippet

Anyway , if I could be of help, I could gladly do it. I will think about it, could even learn more in the way.

While searching the forum I finished this site: http://www.linguenordiche.it (is in italian on northern languages, since is for the university). It’s a "newsite", without commenting or blogging, since it was not requested. Is like a newspaper.
That’s my low level of competence. I have to put my hands on personalization of manager for my users (I mean, just take out the buttons they don’t need to use), login and front end editing, and trying commenting maybe.

I spent most of the time understanding (but not fully) how to deploy getresources/getpage (still have to understand when to use one and when the other >__<), and learning how to get TV trough it.
I also tryied (but failed) to use a snippet found elsewhere on the forums (gallerymaker or something like that) to make the image of the articles don’t show if it was not indicated in the TV. But probably I cannott pass a snippet call in the chunk template of getresource, or I don’t know how to do it:I tryed cached, uncached, but only got null result. But maybe it was thePHP function of the snippett that was written bad (that’s the problem when u are not a programmer: you find really difficult to understand WHY something never goes as you wish ).

Quote from: Erebus74 at Jan 10, 2011, 03:31 AM

I get your point on "complete packages", and when they will be there they will simplify one of the points I was asking for: removing the need to do every time a fresh install, then browse the packages (even if I know what packages I need, I don’t ever remember where they are and I spent every time much time on that simple task). While a complete package or two could do the trick.

This is just a matter of time until someone decides to wrap one up in PackMan, really I can’t promise anything... but I am on a roll regarding add ons in the past month, lol.

For the cheatsheet/examples, I would like to lend an hand, but I feel I’m too inexpert (as I said, I’m not a programmer and still feel a newbie at Modx, even if I’m learning every day more), and I don’t want to make an example and to find I have used a "deprecated" or bad way to use that snippet

Anyway , if I could be of help, I could gladly do it. I will think about it, could even learn more in the way.

Too inexpert? Honestly - there will always be people who know every single detail but they wont need a cheatsheet. The average MODx user is currently a developer, but that should definitely become more focused on designers aswell - and a cheat sheet from your point of view would definitely be useful. Trust me on that.

So please, if you have the time and energy to make one, do it! This community isn’t focused on experts in my opinion - but very open to different levels of knowledge and skills.

While searching the forum I finished this site: http://www.linguenordiche.it (is in italian on northern languages, since is for the university). It’s a "newsite", without commenting or blogging, since it was not requested. Is like a newspaper.
That’s my low level of competence. I have to put my hands on personalization of manager for my users (I mean, just take out the buttons they don’t need to use), login and front end editing, and trying commenting maybe.

Looks pretty good to me. I haven’t seen the back-end, but it looks like it works, so sounds like you’re competent enough?

I spent most of the time understanding (but not fully) how to deploy getresources/getpage (still have to understand when to use one and when the other >__<), and learning how to get TV trough it.
I also tryied (but failed) to use a snippet found elsewhere on the forums (gallerymaker or something like that) to make the image of the articles don’t show if it was not indicated in the TV. But probably I cannott pass a snippet call in the chunk template of getresource, or I don’t know how to do it:I tryed cached, uncached, but only got null result. But maybe it was thePHP function of the snippett that was written bad (that’s the problem when u are not a programmer: you find really difficult to understand WHY something never goes as you wish ).

getResources gets, like the name says, resources. getPage is a wrapper snippet (it includes getResources) that allows you to do pagination.

(I’ve not yet played with getPage tho, but that’s the theory afaik)

Some great feedback and ideas here folks. Documenting and documentation are always a challenge as the people who develop are rarely able to gain the perspective needed to write beginner instruction on what they’ve developed. MODx has some very good documentation and does very well at it but certainly is not perfect and we’re always looking for volunteers or people to request improvements to particular documentation.

One of the key criticisms that has haunted MODx and other projects is that great documentation often ends up on someone’s personal site or blog and it makes it very difficult to locate and then the content author gets busy and it doesn’t get updated or it becomes abandoned.

It would be ideal if as much documentation as possible be put on the official wiki as part of the add-on documentation or in the main documentation.

We are looking at some of the issues Erebus74 discussed about packages and we need to make sure we find a balance between making things easy and keeping installations clean. This may take the form of add-on bundles or possibly distributions.

The fact is that no matter what CMS you choose there is a learning curve and with MODx you’ll find the more you know, the more you find there is to know.

Anything on my website is free to me copied over (with a link back) if it’s considered good enough to be there.


The thing is I also have the feeling there’s a difference between "Official documentation" and my personal take on something.. which is why for example my "MODx - Mod what?" article is on my personal site, and not in the RTFM.

I’ve worked on joomla and wordpress, and also studied a bit other cms, and tried some just for comparation, and I feel that nothing beats modx for a designer who likes control on the page structure and markup.
Indeed when I learn something new in modx I feel good, because It’s not wasted time.
And after the site is up, also for my clients (and for me too) is simpler and faster to use modx that joomla or even wordpress: the folder/document structure is a great visual tool for management, and very flexible.

Expecially joomla, I find it very frustrating. I’ve done this site (http://www.in-wine.com) in joomla, because the clients wanted some very specialized modules I could not do (with my skills) in modx 2 years ago (but I could probably do them now). But every time we have to make a modify in the menu structure, or in even adding some credits etc, we have to create/control the appropriate section, then the category, then the document, and then add it to the menu.
In Modx I would have changed the code of the template, or inserted in a chunk or created a document, but only ONE of this steps for a simple task like that.

Probably is also my tastes, anyway for me Modx is a GREAT tool for my work.