"You've Installed 0.9.2, Now Do This..." - Call For Input

As we all know, the documentation for MODx is all over the place, and anyone moaning about it is generally advised to write their own documentation.

What I am proposing to write is an article which lists all the things that generally need to be done to a MODx 0.9.2.1 installation to keep up with best practices.

This will include pointers to all the updated snippets, so that new users can be sure that they are using the latest versions. (Some key snippets were out-of-date when the version was compiled).

It will also contain summaries of other advisable changes. I don’t intend to touch much on how to go about managing a site - that’s an entirely different thing and the modxhost site does a good job of covering the basics of that.

There is already a thread [0.9.2] Known Issues and resolutions but this is not easy to follow, does not link to the updated snippets, and probably doesn’t cover long-standing issues. The point of my version will be that it will be almost a ticklist of things to do to make sure you are up-to-date, whilst we await the next release. Hopefully it will also help everyone be on the same page, and cut down on repeat queries about bugs that have already been fixed.

I will most likely post the first draft as a thread in Tips and Tricks, and update the top post in a similar manner to the way the Repository post is updated - but if MODx or modxhost want to host a copy as well that will be better.

You can help in two ways:
1) Mention something that you feel must be done to 0.9.2 - ie knowing what you know now, if you were to download the 0.9.2.1 release and install it, what would you change next? Provide a link to more info if you can.
2) Provide encourgement in my endeavour. I will be more motivated to complete this if I know there’s a lot of people who would find this a timesaver.

Quote from: PaulGregory at May 29, 2006, 11:44 PM

As we all know, the documentation for MODx is all over the place, and anyone moaning about it is generally advised to write their own documentation.

What I am proposing to write is an article which lists all the things that generally need to be done to a MODx 0.9.2.1 installation to keep up with best practices.

This will include pointers to all the updated snippets, so that new users can be sure that they are using the latest versions. (Some key snippets were out-of-date when the version was compiled).

It will also contain summaries of other advisable changes. I don’t intend to touch much on how to go about managing a site - that’s an entirely different thing and the modxhost site does a good job of covering the basics of that.

There is already a thread [0.9.2] Known Issues and resolutions but this is not easy to follow, does not link to the updated snippets, and probably doesn’t cover long-standing issues. The point of my version will be that it will be almost a ticklist of things to do to make sure you are up-to-date, whilst we await the next release. Hopefully it will also help everyone be on the same page, and cut down on repeat queries about bugs that have already been fixed.

I will most likely post the first draft as a thread in Tips and Tricks, and update the top post in a similar manner to the way the Repository post is updated - but if MODx or modxhost want to host a copy as well that will be better.

You can help in two ways:
1) Mention something that you feel must be done to 0.9.2 - ie knowing what you know now, if you were to download the 0.9.2.1 release and install it, what would you change next? Provide a link to more info if you can.
2) Provide encourgement in my endeavour. I will be more motivated to complete this if I know there’s a lot of people who would find this a timesaver.

Awesome idea! The more tutorials around the better - covering modx is like walking the Sahara with a blindfold on, but if you have the time then I’m sure it’ll be well received

-Starbuck

May be what’s needed is a wiki? With a bunch of selected users so it dosen’t get out of control?
May be only the admins can write to the documents and the average users can only add to say the talk pages?

Just a tought for what it’s worth!

Starbuck, I like your analogy. I can only hope that my article will be more useful than a map of the desert!

steve_a: A wiki would indeed be more helpful generally in documenting MODx, but I’m writing a specific article with what I hope to be a short-ish lifespan before the next official release comes out. I’ll see how I feel after I’ve written it whether I want to be more involved in the general documentation, official or unofficial.

@PaulGregory -- consider this my encouragement for your endeavors. I welcome any and all contributions to the project and your idea sounds wonderful to me; we need more step by step documentation to ease our growing user base and support burden.

@steve_a (re: wiki) -- as part of the transition to 1.0, we will be announcing public SVN access along with a full Trac site (which is a Wiki) for managing development activities and documentation. However, I’d like to keep this developer oriented while finding a way to evolve the MODx Documentation on the web site into a more end-user focused collection of articles, allowing some form of public documentation contributions (comments and/or article submissions), and direct article contribution capabilities could be awarded to users in a system of meritocracy based on competency and initiative.

That said, I’d also really like to see our documentation done without an external wiki application, using native MODx features and concepts, and allowing contributors to choose their own favorite input format (various flavors of wiki, bbcode, textile, etc.).

The only reason for using a wiki would be the "collaborative editing" side of things; all MODx really needs is an Edit History which stores the text of a page with the date and the userid, then there’s some accountability to the edits. The "compare version" routine could be cribbed from one of the many os wikis out there. This history would work best if it was toggleable per page. Most websites won’t want it on - although it might also be useful to figure out exactly which employee screwed up the homepage. Hmmn. Is this going to be in the next release? If not, I think I need to write this!

Still, as per my top post, if anyone has anything they think I should cover then please remind me. I’ll be posting my first draft sometime this week and it should be clearer then what (if anything) is missing.

Quote from: PaulGregory at May 30, 2006, 01:55 PM

The only reason for using a wiki would be the "collaborative editing" side of things; all MODx really needs is an Edit History which stores the text of a page with the date and the userid, then there’s some accountability to the edits. The "compare version" routine could be cribbed from one of the many os wikis out there. This history would work best if it was toggleable per page. Most websites won’t want it on - although it might also be useful to figure out exactly which employee screwed up the homepage. Hmmn. Is this going to be in the next release? If not, I think I need to write this!

Still, as per my top post, if anyone has anything they think I should cover then please remind me. I’ll be posting my first draft sometime this week and it should be clearer then what (if anything) is missing.

I’ll try and offer what I can on the what to cover front, but being the uber-geek that I am, part of the problem is me identifying what is and isn’t obvious to the less geeky.

And re: wiki -- exactly! And great idea on the revisioning! I’ll make sure the 1.0 codebase gets full support for super-granular revision control. And, to answer your question, yes 1.0 features will include full content-revisioning (by content element, i.e. templates, chunks, snippets, TVs, etc.) with multi-cultural support, for flexible handling of culture-specific content, translation workflow, and more.

BTW, if you are (or anyone else is) interested in contributing to the 1.0 coding efforts, please feel free to contact me privately. Though I do have some very clear principles and goals for the code, I welcome input and/or assistance into some of the decisions I’ve made, as well as the implementation issues I run into from time to time.

Quote from: OpenGeek at May 30, 2006, 02:59 PM

being the uber-geek that I am, part of the problem is me identifying what is and isn’t obvious to the less geeky.

If it helps, here are the three sections I intend to cover:

1) Changes that are already available on the forums that will be in the next release. Whilst these are obvious when you know about them, I don’t think there’s a list anywhere of which core snippets have more up-to-date versions.
2) Other changes to cover potential problems.
3) Pointers to what content changes to make - an example of a non-obvious thing would be changing the keywords.

Of course, nothing beats experimenting with MODx, but this checklist should also be of use to people who are familiar with MODx but are setting up their second/third/fourth installation from scratch. I’m thinking of using a What/Why/How format so that it can be used primarily as a reminder.

I no longer intend to write the "install these upgrades" part of this, as it is surprisingly subjective. (Other than "Install Ditto").

Instead, I’m going to write something which takes people from the basic no-sample-site installation through to a basic site with a working RSS feed and contact form and which will be less 0.9.2 specific.

Great stuff Paul ... I look forward to it. Thank you!