I have been looking at the MODx documentation, which is in many pieces in many places. Lots of things are not explained. Lots of other things are explained multiple times in multiple places.
Things that are easy to figure out are documented by multiple people. So a casual reader might think that there is plenty of documentation.
Things that are hard to figure out, i.e., the things that really need to be documented, are often documented poorly or not at all.
So it occurred to me: Maybe what MODx needs are some volunteers who would improve the documentation.
So I explored further, and have come to the conclusion that such volunteers are unlikely to be found. And here is why.
Consider a fairly well-documented project: the Apache web server. Looking into the source tree, I find that most of the directories contain a README file that briefly explains the layout of the directory and the purpose of each subdirectory. Here and there there is a file in the source tree that explains some of the internal workings. And most (though not all) of the source files are sprinkled with comments throughout that are helpful to understanding what the program is doing. And each Apache module has a built-in documentation syntax, with each possible configuration setting described. So you can actually query an Apache server and it will tell you which modules are loaded and the options accepted by each module and the syntax and purpose of each option.
And we have all this before anybody begins to write even one line of a user manual.
At this point, somebody can dig into the source code, and with a little effort come up with a pretty good idea of how things work. At that point the user manual is half done already. All that remains is to fill in the holes by asking the developers an occasional question and by doing some test runs.
Result: A non-developer can write useful documentation.
Result: The world’s best free web server, accompanied by some pretty good documentation.
Now let’s look at MODx.
Almost NONE of the above applies here.
No README files. Almost no comments in the code. No self-documenting syntax anywhere.
So in the case of MODx, the only people who could write useful documentation are the developers, i.e., people who are already familiar with the code and know what it does.
And these people are fairly busy writing code. The documentation they have time to write may be all that we will ever get. Unless they can add more README files, more comments within the PHP files, more self-documenting options, etc., this project is probably doomed to having few or no volunteers who will focus on the documentation.
A person who wishes to contribute documentation needs the raw data somewhere, and MODx provides very little.
Rahul
MODX Staff
