I would gladly pay a subscription for well-debugged and documented service, so I'm even more surprised that the docs are the same for paying customers.
The thing about documentation is that it has to work for newcomers. If the learning curve is too high (particularly if for no good reason), people will turn away and look elsewhere for a CMS. And there are plenty of them around these days. MODx's market share of CMSs is not great: <0.01%. While MODx staff advertise any notable results for MODx usage figures (eg "5% of market share in Russia"), whenever challenged on the global share, the answer always given is that MODx is for developers, not everybody, and isn't supposed to be as popular as Wordpress.
I just read a blog piece in
https://modx.today entitled "Why isn't MODX more popular?". There's even a section in it, "Asking the Right Questions", but it never once mentions documentation. There is much of the usual stuff about why MODx is NOT meant to be popular, why it isn't so easy to discover etc. There's also a plea that the "company behind MODX doesn't have the budget or resources that Automattic has, making it harder to reach a large group of people with advertising".
So MODX DOES want to be more popular.
Ironically, documentation IS mentioned, but only in the "About the author" section: "the CEA (Chief Executive of Awsomeness") at modmore where he helps people doing more with MODX. He accomplishes this by providing premium extras with great support and documentation, and other initiatives meant to help MODXers around, like MODX.today.".
So documentation IS also valued by MODx staff. But why not MODx documentation?
In my experience, this author and all the other MODx team have done great things in producing this CMS. But after ~10 years, it is not going ballistic, like it should. There's been a lot of mutual back-slapping going on, but there's too much obsession with new features (I've been saying this for years). There's always so much effort to develop and launch new features with the result that (normal, not super) users like me are constantly on the back foot with new bugs and ever-out-of-date docs. I don't even NEED new features! The MODx team need sat down by their Mums and told that it is GOOD ENOUGH and to stop developing new features and get the bugs fixed and get the documentation overhauled!
Otherwise it will be overtaken by every other CMS out there.
Has there ever been any type of study into how effective the docs are? How long it takes complete novice users to set up a site for the first time? MODx should have a set of well-defined tests and run them at least once or twice a year with novice users. Basic sites with n-pages and features X, Y and Z shout be up and running within an hour with no other help than the docs.
New users need to have a good experience. Bad feedback goes out there and never goes away.
There is a huge amount of effort in the production of marketing and other MODX-related copy. In
https://modx.com/blog there are 2-3 articles per month, mainly updtes about MODX Cloud.
https://modx.today is crammed with interesting stuff (though I only discovered it today). It would seem logical to have similar regular effort in MODX documantation.
Missing a key feature entirely from the docs for FOUR years just aint good enough! Static Elements should have been in there as soon as it was released. Particularly as it was and has since been presented as a useful new feature. How many people have searched for that? And I might add that the screenshots on the Creating TVs page are nothing like the 2.3.5 I'm using.
It should be part of MODx's workflow to produce accurate and complete documentation for every feature added or updated. Even if these are dry technical descriptions, it doesn't matter, as long as they are accurate and complete, other people can fill them out into more readable text with section headers, examples and screenshots. It just has to originate from the developer in the first instance, as part of their deliverable. These initial docs can be published as "version 1" or whatever until they are tested and edited.
I'm not just having a moan here for my own sakes, but for MODX too. If there was less focus on the opinions of users that love MODX and more effort made to get feedback from those that don't, didn't, or couldn't, then MODX might start to take more of the market share it really should have.
~
BTW Bob, I do have your book, but rarely read it because I travel a lot and it is 2x the weight and 4x the size of my laptop! Why don't you publish it as a subscription-access website for folks like me? (Then it would be easier to update and correct too!
).
As Michael Joseph points out in his comment under "Why isn't MODX more popular?": "Time is money to any web professional". If MODx is aimed at web professionals, and no-one can fugure out how to create good docs (like Wordpress do) then for goodness sakes let us pay!
[ed. note: Gav last edited this post 8 years, 2 months ago.]