[Draft] State of the Ditto

What’s the additional lag on 2.0?

On the Wiki
The way I see it, the Wiki isn’t necessarily the official location for support, but is instead a user-edited guide to the entirety of MODx including add-ons. Many questions, like "How do I build a dynamic menu?" would, in pure framework terms, only be answered by "Write a snippet or find a snippet someone has already written". That’s a great approach for any official read-only MODx documentation, but the Wiki can see things in the wider context, and link to pages about the snippets, which in turn can reference documents anywhere.

For example, the official documentation can take the form of screencasts, but if people want to repurpose that content into a wiki, they should be able to add it to the MODx wiki. After all, a "How to add a Blog" article will use multiple snippets. While duplication of information is bad, multiple overlapping sets of instructions in different formats is a good thing, and the wiki is a natural hub for links to where-ever.

So, I’m firmly on the side of "AND". Ditto site AND wiki. (And, in basic form only, the official MODx documentation). I think it is up to the author where they host the official stuff, and there should ideally be only one official source, but I equally think it is up to the contributing users as to where they host their own documentation (be it their own website, a magazine or the wiki). Bouncing about the web aimlessly is confusing; bouncing around following clear links between sources is what it was meant for.

Perhaps we could add all the various info sources to a Google Custom Search Engine?

On the version numbering

My view is that if you make public a beta of 1.1 (or whatever number), you should bring out a final of that same version number *unless while working on it you have had to decide to break compatibility in a greater way than any previous minor release*.

So if you’re saying that it’s easier to go to 2.0 than complete 1.1 and then complete 2.0, then go for 2.0.

Going from 1.1 Beta 2 to 2 Beta 1 may however be confusing, so I’d keep the beta numbering going and go straight to 2.0 Beta 3.

My concern with multiple disparate sites for "core snippets" is what happens if an author drops out of the project? And then their hosting expires for that resource. And a lot of valuable documentation for a snippet that’s distributed as a "core snippet" goes away?

Answer: either the resource is abandoned, or there’s a mad struggle to piece it all back together. Either way, it hurts the community, or at best is a legitimate inconvenience. (IMO, that could be completely and easily avoided.)

For example, several years ago, a friend and I had a fully working and supported CSS template structure of Zen Cart when the project was brand spanking new. No one else on the team had a clue about CSS/XHTML sites or how to maintain them. It significantly cut down on site sizes and rendering speed, and was a net-positive for the project. When five of nine core team members (us CSS-heads included) decided that their time would be best-spent elsewhere, the CSS-efforts languished and were ignored mostly. Only in the last year or so have they finally gotten back up to speed there, if they have at all (not sure). The reason: there weren’t really any standards, expectations or requirements for documentation, or source control for that matter.

I’d rather see the documentation and source code maintained for core snippets (ditto, eform, wayfinder, etc) in a location that multiple people living in different locations around the world, that are not likely to all be flying on the same plane at the same time, can readily access and keep up to date should someone drop off either permanently or for extended periods of time.

Quote from: rthrash at Dec 18, 2006, 09:48 AM

My concern with multiple disparate sites for "core snippets" is what happens if an author drops out of the project? And then their hosting expires for that resource. And a lot of valuable documentation for a snippet that’s distributed as a "core snippet" goes away?

Answer: either the resource is abandoned, or there’s a mad struggle to piece it all back together. Either way, it hurts the community, or at best is a legitimate inconvenience. (IMO, that could be completely and easily avoided.)

For example, several years ago, a friend and I had a fully working and supported CSS template structure of Zen Cart when the project was brand spanking new. No one else on the team had a clue about CSS/XHTML sites or how to maintain them. It significantly cut down on site sizes and rendering speed, and was a net-positive for the project. When five of nine core team members (us CSS-heads included) decided that their time would be best-spent elsewhere, the CSS-efforts languished and were ignored mostly. Only in the last year or so have they finally gotten back up to speed there, if they have at all (not sure). The reason: there weren’t really any standards, expectations or requirements for documentation, or source control for that matter.

I’d rather see the documentation and source code maintained for core snippets (ditto, eform, wayfinder, etc) in a location that multiple people living in different locations around the world, that are not likely to all be flying on the same plane at the same time, can readily access and keep up to date should someone drop off either permanently or for extended periods of time.

First of all, this term "core snippets", or "core add-ons" needs to go away; it’s an oxymoron. A selection of example snippets distributed with the core I’d buy for a $1.

Second, add-on projects are add-on projects and are not MODx. They IMO, should be maintained and developed in the same way MODx is, by a community with vested interest in doing so. However that community should be maintained is up to that project. Period. If the developer wants to host add-on code and documentation and bug tracking at Google Code, well, more power to them. It increases exposure to MODx and at the same time keeps the focus of MODx on being a framework and transfers the responsibility of the add-ons where they belong, isolated from the core.

Finally, if the add-on is released under an open-source license, the author dying or discontinuing individual support is not really much of an issue then is it? If the project is popular enough, it will have multiple contributors and responsibility with be distributed anyway. If you are worried about physical project resources and artifacts, this is going to be different for every component developer we attract to MODx, and trying to make them all do it our way is going to end-up being a bigger drain on us, and a bigger roadblock for potential contributors, than any other thing. The rules and standards for making documentation available and any other similar best practices, can be managed without forcing a variety of contributors into a single square hole, and those that want to use our square hole to host quick-and-dirty contributions have that option.

What about installing TRAC on modxcms.com? Then we have everything on one central location.

That should be doable indeed. We’re trying to decide how the full blown support/ticketing will be handled in the very near future in fact... lot’s to decide there.

Some exciting things are coming in the near future! I have 3 weeks off for Winter Vacation and its time to put the coding engine into high gear! What follows is a brief of what is coming down the pipeline.

Documentation:
There is much work needed on this subject. I have deemed that screencasting is the best way for me to make the documentation. It is quick and efficient --- no screencapture issues. If someone would like to take the screencast

Planned Tutorials:
I hope to use iShowU to create the following tutorials. Disclaimer: These are in no particular order.

How to setup a basic blog
How to setup tagging
How to setup filtering
How to setup archives using Reflect
How to create a custom template
How to create an RSS, JSON, or XML feed

Releases:
Ditto 1.1 (now in Beta 2) will not be released under that version number. I have decided that it makes more sense to release the codebase as 2.0 since the paramater list has been refined so that there are no superfluous items.The release will have the following changes:

• Revamped document parser
• Re-architected codebase for maximum performace
• phx support
• New template placeholders
• New Reflect archives
• Completely new filtering system which allows for conditional templating and much more
• Ditto Extenders (name TBD) which will allow users to create simple addons that alter Ditto’s behavior

There is a thread for Ditto 2.0 Feature Requests [HERE]

This release will be accompanied with a migration guide so that upgrading from 1.x insulation will be a breeze.Furthermore, the Ditto TRAC site will be turned public simultaneously with this release.

Stay tuned...

Good stuff.

Things that leap out:

Missing "and transcribe and translate it, they are welcome to do so. And indeed that’d be nice." (or equivalent) at end 2nd para.

parameter not paramater in Releases para.

And there may be merit in inserting something after "TRAC site" at the end to explain what that means.

on the side issues raised in this thread
Quote from: OpenGeek at Dec 18, 2006, 10:35 AM

First of all, this term "core snippets", or "core add-ons" needs to go away; it’s an oxymoron. A selection of example snippets distributed with the core I’d buy for a $1.

This is a fundamental that needs addressing. I would argue that MODx as rewritten by Jason is the CMF; MODx as expanded upon by Mark et al is the CMS.

Yes, "core snippets" is wrong, but they’re not just "example snippets". If they were example snippets they would be heavily documented Hello World jobs. They are more like the common applications in Linux distros, there because they are useful rather than because they are good examples. If I’m following posts elsewhere correctly, Jason doesn’t use any of the snippets from the main distribution. From that perspective, it would be very easy to underestimate their significance to the average MODx user, and their significance to the wider MODx system.

The MODx documentation should be purely about the framework, with a few pointers to the Repo.
The Repo should contain sufficient information about add-ons from the author(s) and source code... of course, there are no compiled parts to MODx so there’s no real distinction.
Work-in-progress (betas) and official support should be hosted wherever is most convenient for the author. This may of course be a commercial application and/or support from the author might be on a commercial basis.
User-generated user-to-user support may additionally be in the MODx forum, and that seems to be the natural place for communication between MODx users.
User-generated documentation should be in the Wiki.

It might be that authors prefer to use the forum as the place that they host betas and give support.

In the specific case of Ditto, I don’t think that the Ditto pages in the main MODx documentation ’fit’, but other than that everything seems to follow sensible practices for a project of this scale.

I would also argue that people are more likely to contribute towards hosting costs if it is the centre of their MODx world rather than if it’s just a place that they download updates to the core from.