That’s exactly my point.
Mats Wall raises a valid point about documentation being able to help aleviate the load of the team. I agree the doc could be user oriented like in the WordPress Codex : advanced, intermediate, basic users... and also agree about a FAQ (I did one for the french forums).
True, but then again you can at least tell them to read the f***ing manual! (Pardon the language.) They can’t expect you to feed them the answer when it’s clearly written in the documentation.
Yet, I’ve learned something in the various community I have contributed to : the benefits of a well thought-out and comprehensive documentation is not as high as you would expectSame goes for the FAQ, unfortunately (even if it’s more efficient than doc to aleviate the load).
First, Help Vampires won’t read itThey’d rather have you quote it to them... and ask you twice the same question nonetheless...
I agree that documentation writing is an art in itself as it demands a high level of technical knowledge, pedagaogy and writing skills. But this doesn’t mean it can’t be done. And it *must* be done, especially in a complex project like MODx!
Second, writing documentation is harder than it seems : technical writing is an art, if you take into account the user-oriented part of it (which is a pre-requisite if you aim low skill users), then you get yourselve a big workload not only to write but also to maintain it (something pretty hard with MODx speedy development).
Right, but this doesn’t in any way solve the problem how to bring down the number of simple support questions on the forums. My question is (as I pointed out to Zi), What to do with all the people coming in who are not as advanced as you would like them to be? That’s the key question here, IMHO.
The reasonnable thing to do then is to write a technical doc, that might not be user friendly and thus, won’t get the number of questions down on forums. Of course now, as Ryan says, if you have loads of cash to pay people to write user friendly doc, that’s another matter... but even if it was the case, I fail to see how it fits the goal of MODx which is to provide a highly versatile tool to skillful people. "Dumbed-down" (and thus rigid) web applications numerous enough as it is, and are precisely what we don’t want MODx to become otherwise it will loose the versatility we love so much.
Now, does that mean the documentation should not improve ? Of course not. And if you watch closely, it does improve regularly. But my take on this is we should really boost the documentation process once MODx reach the 1.0 release. Things will change drastically in some areas and I’d rather see time spent in developping those amazing concepts that will be in 1.0 be done as fast and as well as possible. Also, I believe MODx should not aim to be end-user oriented, at least the core team should be able to stay focused on the core goal which is to build a highly versatile content management framework.True, but what to do in the meantime? I’m sure you realize that if enough people come to MODx and get put off by numerous off-limits signs, it can be very damaging from a PR perspective. So the question remains what to do about it. To put your head in the sand and wait for the all-encompassing 1.0 is IMHO not a good solution.
MODX Staff
LOL...!
Mats, by nature or your use of the term "pedagogy" you just demonstrated your insightful grasp of the written word. Thank you for volunteering to write our FAQ for us!
Point taken!
True, but then again you can at least tell them to read the f***ing manual! (Pardon the language.) They can’t expect you to feed them the answer when it’s clearly written in the documentation.
I agree that documentation writing is an art in itself as it demands a high level of technical knowledge, pedagaogy and writing skills. But this doesn’t mean it can’t be done. And it *must* be done, especially in a complex project like MODx!
Right, but this doesn’t in any way solve the problem how to bring down the number of simple support questions on the forums. My question is (as I pointed out to Zi), What to do with all the people coming in who are not as advanced as you would like them to be? That’s the key question here, IMHO.
True, but what to do in the meantime? I’m sure you realize that if enough people come to MODx and get put off by numerous off-limits signs, it can be very damaging from a PR perspective. So the question remains what to do about it. To put your head in the sand and wait for the all-encompassing 1.0 is IMHO not a good solution.
MODX Staff
Dear Zi, I hope this comment isn’t leveled at me personally ...
True, but what to do in the meantime? I’m sure you realize that if enough people come to MODx and get put off by numerous off-limits signs,The reason they would be put off is not off limit signs, it would be that MODx is perhaps not the right solution for them. The MODx core team have never claimed that MODx is an end user friendly framework. It is a development platform aimed at people with some knowleged of PHP, and an expertise in CSS and XHTML. Will it work for folks without those credentials? Sure... It has... I am one of them. But it worked because I took the time to learn PHP CSS and XHTML. This is because I had a vision in mind of my webspace. MODx is the tool with enough flexibility to allow me to do whatever I dream of (*I have not failed, just found 10,000 ways that don’t work, etc...). But it did not come easily. It was not as simple as install, click, manage, run! But because I can program, and I know CSS and XHTML, MODx explodes the boundries imposed on me by most CMS’s. It is a framework for developers. There are lots of CMS’s that are end user friendly. check out the list at http://opensourcecms.com . I am sure there is something there more suitable for your needs if "user friendliness" and "documentation" are your main concerns.
MODx speaks for itself. the developers who have used it are fanatical about it, and word has spread quickly... Very quickly! I think what we are dealing with hear mats, is either a misunderstanding of the target audience or you projecting MODx onto a target audience it is not yet intended for. I don’t know how many times this has been addressed in these forums, so I will repeat it. "MODx is a content management framework, aimed at developers to help them quickly build their web applications".
it can be very damaging from a PR perspective.
The answer is... If you are stone set on using MODx, learn PHP (at least to a basic/intermediate) because there is more documentiation in the comments of the php files than there is on this website... Read the comments! Second, master CSS and XHTML. you will find when you meet those prerequisites, MODx feels so natural! There are numerous books on PHP, CSS, and XHTML, as well as free online tutorials (that’s how I learned most of this crap
So the question remains what to do about it.
) so head over to google and get your ducks in order.Then be proactive man! Go learn PHP, CSS, and XHTML. Disect the .inc files and the classes, pull out the comments, and write a FAQ. the info is there, and If you looked around, you could find it. The goal here is not to provide people with the knowledge base that is a prerequisite for getting the MOST out of MODx, it is to provide those people that already know PHP, CSS, and XHTML, a superior tool for creating web sites and web applications very quickly. Do not confuse the two.
To put your head in the sand and wait for the all-encompassing 1.0 is IMHO not a good solution.
I think I want my money back
That’s my 2¢.
Best regards,
Mats
MODX Staff
I don’t know if I would have grasped PHP so quickly (though I hear as far as programming languages go, it’s a pretty easy one) if it weren’t for MODx. As a matter of fact, I probably wouldn’t have had the motivation to learn PHP if it wasn’t for this encouraging community willing to help with my (arguably simple) questions, and pointing me to online resources. I would probably still be a patient bystander. Now if feel marginally comfortable solving my own problems, and sharing any useful solutions with the MODx forum members. It is a fostering commune, this MODx forum!
MODx is actually a great PHP learning platform.
This discussion is closed to further replies. Keep calm and carry on.