Good pro-MODx arguments needed

Jason (OpenGeek),

If your vision intends to drop the addons, snippets & etc. from the core then sure the documentation can be focused on the MODx engine.

My own incomplete and possibly naive opinion is that if MODx becomes too bare bones the curve for new users will get higher no matter how "complete" the API and code documentation are. I would be interested to learn more about your overall vision (though I think I have had some glimpse into it from some of your posts and items on the site here and there).

I like that MODx comes with snippets ready use and install. I would rather opt out of their use than have to build up a minimum of functionality. Maybe I am missing the point or missing out on your wisdom. What will the new MODx do out of the box? Will a decrease of specific functionality lead to an increase in workflow? Will it lead to decreased efficiency for multiple unique projects? Will it require a higher cost to the end user in longer development times? I don’t know so I am not suggesting that I know these answers or that in any way I could form an opinion about the actual outcome as I am not much of a devloper.

Quote from: BobRay at Feb 07, 2008, 09:39 PM

The Red-Bean Subversion book is a perfect example of what I’d like to see. If there were a TortoiseSVN video, I don’t think I’d ever watch it.
Bob

BobRay,

The premise of the Red-Bean SVN book is tremendous, full featured guide to using Subversion. With no intended offense to its authors it is pretty confusing and unnecessarily technical in places and clings to foo examples. That being said I hope that MODx can muster up a less convoluted document for teaching people how to do MODx. But, a single resource for all the documentation is the ideal situation no matter how it is achieved.

By the way, there are a few videos out there on using Tortoise and I found them helpful. I actually watched one on using Vendor Branching with CakePHP to try to figure out a good way to use it with MODx (still haven’t worked it all out).

All the best,

Jay

@ Maaike,

I heard about Modx and did visit the forum and the Modx CMS before you mentioned it, but I was not sold after reading the homepage’s content. Thought I admit me did two sites in Etomite made the transition easier, but you sure did a wonderful job in converting me to Modx I don’t, however have the same luck every time I tried to convert others.

@ DavidM,

Wow, Xpat looks interesting. I have a fondness for Textpattern, but it’s development has been discouraging. Will keep an eye for this new baby!

Quote from: smashingred at Feb 07, 2008, 09:51 PM

Quote from: BobRay at Feb 07, 2008, 09:39 PM

The Red-Bean Subversion book is a perfect example of what I’d like to see. If there were a TortoiseSVN video, I don’t think I’d ever watch it.
Bob

BobRay,

The premise of the Red-Bean SVN book is tremendous, full featured guide to using Subversion. With no intended offense to its authors it is pretty confusing and unnecessarily technical in places and clings to foo examples. That being said I hope that MODx can muster up a less convoluted document for teaching people how to do MODx. But, a single resource for all the documentation is the ideal situation no matter how it is achieved.

I didn’t mean to suggest the Red-Bean book is perfect and you’re right that it is unnecessarily technical in places. I’ve been reading "foo" examples since before time began and I still hate them with a passion.

That said, I think it’s actually very well organized considering the complexity of the topic and many of the sections (e.g. the "you and Sally" stuff on branching and merging) are extremely well-written. I’ve never had any trouble finding what I wanted in it, even as a newbie. I wish I could say the same for the MODx documentation.

Bob

I think a big issue with comprehensive documentation is that everybody is on a different kind of server, using different client applications and everybody wants to do something different (which is probably why they’re using MODx in the first place).

Installation is very simple, Download. Unzip. Upload. Click Install now. Follow the instructions on the pages. Right? Wrong.

Look at how many people have all kinds of problems with installations, everything from their archive program not able to open the archives or corrupting files as it does so, to ftp clients skipping or corrupting files during the upload to servers with unusual configurations causing session problems.

So how does one write a comprehensive guide to just this one simple function of installing MODx?

Quote from: sottwell at Feb 08, 2008, 01:05 AM

So how does one write a comprehensive guide to just this one simple function of installing MODx?

Good question. Perhaps a comprehensive guide is too much at this point.
What I would like to see would be a guide that explains the basic concepts of MODx (there’s quite a bit of this already at the MODx site, but some of it is outdated), and contains lots of examples. Such as:

• Building a simple website
• Building a dynamic menu with Wayfinder
• Creating a blog with comments with Ditto and Jot
• Adding a site search
• Writing a simple snippet
• Building a webshop
• Different examples of working with chunks and TV’s
• Best practices
• A troubleshooting section that covers some of the most frequent problems

I agree that often people want to do different things and you can’t possibly cover everything. However, there are also many things that are very common. When you’ve thoroughly mastered the basics, it gets easier to come up with solutions for your own special needs.

Susan, I disagree with the futility of a comprehnsive guide (guide being something that facilitates operation). Sure people have install problems and some people don’t know how to edit or rename the ht.access files or many simple things that many of us take for granted and that is where assumption statements come into play. We assume a minimum knowledge level, we assume a minimum stack, we assume that there are certain tasks that most people will want to do.

I certainly don’t think any attempt should be made to fully document everything about MODx--there will still be forums for exceptions but I think a guide is reasonable and doable with a set of clear objectives and assumptions. I look at examples from the web and the CakePHP manual, WordPress Codex (although it has problems), SugarCRM manual and others that offer great instructional narratives over academic and semantic documentation.

In my opinion, a incomplete single reference is better than a web of scattered and inconsistent references as contradictions, and ideosynchrasies in basic visual formatting can slow the learning process unnecessarily. Much of the information we talk of exists in one form or another but it should not be some hazing ritual that we all have to go through to get to the same place. We should look for every opportunity to make the next group of newbs have an easier experience getting into MODx (without changing MODx or its aims).

As always, all the best,

Jay

Quote from: ganeshXL at Feb 07, 2008, 10:11 PM

I’m not a big fan of video tutorials either. They’re very good for learning Photoshop or Flash tricks (visual apps), but for code-related stuff, I don’t think so.
But hey, horses for courses, as the old folks say

What I like about visuals is that they can often show how easy or complex a particular task is. It may be that the marketing of MODx may benefit more from the screencasts than tutorials. I plan on using basic screencasts along with written documentation for my larger client projects. Sometimes you wonder why anyone did them at all though.

I’m on the side of the fence that having the docs in a single spot would be tremendously beneficial, even for 3rd party stuff. And love ’em or hate ’em, screencasts (well done ones anyway) are a great marketing and learning tool.

Wiki, wiki, wiki!

That’s all I have to say.

Shaun

Shaun,

If the wiki was moderated and there was a set of editorial guidelines so you didn’t end up with the wild west of formatting, levels of assumptions and instant obsolescence, then sure a wiki. The wiki based TineMCE manual is not bad (not perfect but not bad.) I still think that edited, manual beats a wiki any day as a decided voice, tone and editorial style makes for easier learning better explanation and most importantly decisiveness. Wikis are inherently collaborative but unlike an OS project rarely has a captain or leader to say how and why? The current wiki is shaping up to be a great resource for tips and tricks and user submitted documentation but a wiki is seldom a manual or guide.

The reason I have learned PHP (basics) so quickly is not from Wikis it is because I have read a number of well written books by individuals who have a single voice (so I can get used to the way they write and explain things) and I can get into learning. Books are always more powerful than collaborations as the subjective viewpoint is often a great vehicle for undersanding.

I think for the benefit of MODx a "Guide to MODx" needs to be focused, edited and singular with a set of links to references, howtos and wiki posts. A manual is a sign of maturity and although MODx is still a baby compared to other projects it is almost ready for school. We need to look at how we can allow for the most successful adoption of what many of us believe is a revolutionary CMS/F App.

This is also why I think a book in conjunction with the release of 0.9.7 GA is both doable and a potential pillar on the road to 1.0.

Jay