Quote from: OpenGeek at Jul 14, 2007, 12:05 PM
Quote from: smashingred at Jul 13, 2007, 10:09 PM
My vote is to migrate the entire Documentation to the Wiki as having docs all over the place is irritating, even for those of us who build sites in MODx all the time. There needs to be a single location for everything. Not only for the Documentation but also for every new successful snippet, plugin and whatnot--whatnot because of the changes to the base that will result in new names. Also I would love it if snippet authors who have public snippet releases could place their snippet docs on the wiki instead in a number of cases (Ajax Search, Ditto, Wayfinder) all have yet another place we have to go to find information.
I am willing to help out as well as make needed reference updates.
Again the wiki should become the encyclopedia of MODx. Down with the site based docs. Wikify, and keep it live.
While I understand your concerns and points, I do not agree that wikifying everything is the proper solution. The wiki is fine, but is a community-sponsored and maintained resource. It is not a resource for official documentation. And because I want to have official documentation in HTML, PDF, CHM, and other formats, I want all documentation for the core in DocBook format that can be interlinked with the upcoming API documentation (produced by phpdocumentor), and then generated to any of those formats easily. If we need to find a way for registered users to edit DocBook documentation with a wiki-like or similar syntax (I’d prefer textile myself), I’m fine with that (thought think it would be very difficult), but I do not see the current wiki as a long term solution to the documentation conundrum.
Documentation for add-ons and extensions are separate from the core, and I believe they should be kept separate so they can be maintained by the copyright owner in whatever way they feel most comfortable doing so.
And ultimately, since the Wiki already exists, and is an open, public resource, nothing is stopping you from Wikifying any documentation you want to. It may well happen that the public wiki becomes the source for many an official tutorial or other content within the official documentation.
In my experience with reading and writing documentation (often, not as carefully as I should), the real problem is that you need three different types of documentation for any complex system.
1. You need a complete, well-organized reference document, which is what you get from something like phpdocumentor. For exceptionally gifted or perseverant people, this is all you need. Unfortunately, for most mortals, it’s no good at all unless you already know everything that’s in it. You need to know the name of what you need to use in order to look it up. When you do look something up, it tells you what each option does and how to specify it but not why you’d want to use it or when. If you want to create a particular feature for your site, you often have no idea where to look for the resources to do it. In fact, you often can’t recognize what you need even when you’re looking at it. I’ve read the descriptions and documentation of some snippets over and over and still don’t actually know what they do, even though I’m fairly fluent in php. The pages and pages of questions on some of the snippet forums tell me that I’m not alone.
2. The second thing you need is tutorials. These are critical for beginners but are very frustrating to wade through for experienced programmers because they eat up a lot of your time and usually don’t end up doing what you want to do. Nothing is more frustrating than slogging through a tutorial for a few hours only to find out that the thing you’re studying won’t do what you want.
3. The hardest kind of documentation to create, but the most useful to a newbie, is a general guide to the system. It tells you what can be done (and what can’t) and how to approach solving a particular problem. It’s organized by general features rather than by snippet, plugin, or chunk. So rather than "How to Use Ditto" it tells you stuff like "How to create a blog," "How to create a forum/discussion group," "How to create a contact form," How to create a photo gallery," etc. Along the way, it explains the choices open to you and the advantages and drawbacks of each one.
When new users complain about the MODx documentation, I think they’re really asking for number three. I’ve often found myself with a particular problem to solve in MODx and been frustrated that the MODx documentation was of almost no use to me at all. The wiki is somewhat better, but still falls short in that department. Unfortunately, it’s hard to find someone who’s motivated to create the third kind of documentation. When you create a snippet or plugin, you feel responsible for documenting it. Some excellent Samaritans will also create a tutorial when they solve a particular problem themselves. But few are motivated enough to back off and put in the effort to create a general guide to solving problems with MODx and those who know enough to do it are usually incapable of doing it because they’re so familiar with the system that their explanations are not at a level that’s accessible to a new user.
The ideal solution, in my experience, is for a relatively new user who has just figured things out to create something like this with feedback from the code wizards (who, for excellent reasons, usually don’t have the time).
Thanks for bearing with me through this too-long post. About now, your thinking that I should have put the time I spent writing it into creating some useful documention.
As soon as I get a little better grasp of some things in MODx that are still fuzzy to me, I probably will. I’ll probably wait until 0.9.7 to do anything definitive because it sounds like it will contain some major changes in how new users will see MODx.
Bob
MODX Staff
MODX Staff
☆ A M B ☆