I'd be happy to help where needed.
This is an interesting discussion, so I thought I'd throw in my two cents as a developer who has committed a significant amount of time to learning the ins-and-outs of MODX over the last two years.
Documentation within an Open Source project is a touchy subject. There is no agreement on the nature, audience or quality of the docs because of a very obvious reason - these projects are communities that bring together many different groups of people. Developers, users, admins, etc... We all need to recognize that documentation is within the eye of the beholder, and that the documentation is not meant to develop your application for you. MODX is not a pre-packaged, ready to go website that you simply download and vomit onto the WWW. MODX is built around the idea of a 'framework', which is why it works so well for professional implementations where Joomla, Drupal or the like would just not do. You should not expect that the power that comes with MODX can also include an entire pre-packaged, ready to go website. This is the opposite, which is why it works. I can develop on MODX. I hack, compromise and extend for days within most other CMS tools, only to throw my hands up and just hand code it all. Open Source CMS have gotten to a point where they're so bloated & closed that they're unusable, unstable and (excuse me for being blunt), worth absolutely nothing to developers, their employers and their clients. This is where MODX comes in - if it wasn't for MODX, I would have advised my company to purchase a proprietary system as there is simply nothing else like this system. Likewise, when I first showed my boss MODX six months ago (which now development has been finalized on, deployed onto the web, screaming success all around), she immediately asked "how much does it cost", and then took a while to register that the system was in fact available open-source.
This community is living proof that Open Source technologies are a significant force towards the future of software. There is nothing like this, whether free or for-pay, and before I've ever had the chance to criticize documentation within learning the system, I think of the Devs who dedicate a huge portion/all of their time to provide the community the core system and its extras, as it very well could cost thousands of dollars otherwise.
Documentation is a community effort; therefore, when you see insufficient documentation, it should be seen as a call to get involved. Knowledge is power, and its not free. You'll need to work at it - even as a developer, I have spent countless hours combing through the documentation, attempting to put the pieces together to get MODX to do what I needed it to do. I have not once been disappointed, and neither has my employer. In fact, our organization's requirements for the CMS were so tight that they did not expect to be able to find a system to fulfill them - I told them about a system that we could make meet the requirements through customization, recommended MODX and just today, received the highest praise from company execs. The content managers/users are still in awe of what we were able to do for them with MODX. All this and it's only been deployed for two days now. That's a huge advancement/achievement in my career when I am able to provide a company of 350 employees the tool that solves each and every problem of their past through customization by a developer. You can't even buy this type of advancement. Anyone who experiences it knows that we owe everyone on the MODX team a handie. Just saying... this is not easy - not for MODX themselves or the community extra developers. It's mind-numbing, life consuming work that for some reason, many of those who are not developers fail to understand. (Which I can't understand why... there's a reason you think we developers have some screws loose when you meet us, we've been up for three days working on code!)
That said, I do not believe we can hold the community developers accountable for documentation lower than the developer-level. They invested the time in coding it, they do not work for us, nor do we pay them. That, to me, says beyond documentation about high-level code & inner-working, they're off the hook on dumbing it down. That should be on the community. People like me - developers who are able to use what they've made, interpret it and make it a custom piece of their application. I make documentation about it for the company I work for, like most developers, and there is no reason not to make that, my experience with the extension and what I was able to do with it available to the community.
Likewise, if a non-developer has gained experience that could help other non-devs, it's up to them to add this experience to the community. No developer I know has the time to write four different versions of their docs and include various case studies. In fact, most devs I know do not even know how to write non-technical versions. Simply put, documentation is up to everyone. Next time insufficient documentation is found, I invite you to consider it asking for your help rather than it inherently being low-quality.
MODX development moves fast - its unreasonable to expect perfect documentation on such new features. There should be a call to action to the community for knowledge, experience &/or case studies that may be useful for documentation. I, for one, have no problem contributing what I know, assurance of quality, expansion where needed and code samples if appropriate. Some quality standards & a quality assurance process and we can get documentation up to speed.
I am able to provide contributions if needed as well.
MODX Staff
☆ A M B ☆
MODX Staff
