Contributions to the MODx Documentation

Over the past couple of months I’ve been finding all the different sources of MODx documentation annoying, so I had a chat with Jay Gilmore (SmashingRed) and I’ve decided to volunteer and contribute to cleaning up the MODx Docs.

At the moment I’ve been working on this on my own (only for a few days); but I wanted to get the communities opinion on a few things.

Jay has told me that the MODx Team really want to switch off the ditto.modxcms.com and the wiki.modxcms.com subdomains - those two sources of documentation have caused my own confusion (and my clients) many times; and it makes sense to consolidate all the documentation into one place.

I’ve started by moving the Ditto Docs over to the new Confluence System; Jay’s informed me that once its all been moved over they can switch off the subdomain; and last night I needed the AjaxSearch for a client’s site, so I decided to start moving those docs from the old MediaWiki to the new Confluence System.

But I’ve ran into a few issues; the MediaWiki code doesn’t seem to be completely compatible with the new Confluence System; so its not a simple copy-and-paste job; it took me over an hour to get the new AjaxSearch docs to where they are now by doing it manually; and the Ditto Docs are even harder to copy-and-paste since they’re not in Wiki format at all and the HTML for the pages has been badly generated - Jay also mentioned that the core MODx Team don’t have FTP access to the ditto.modxcms.com subdomain as it was setup by a contributor who’s parted ways with MODx - Has anybody got any ideas for a quicker way to transfer the information to the new system?

Once the information is there I’m happy to go through it line-by-line and update it; since I’ve noticed lots of the version numbers, release dates and contributor names are now incorrect.

I know Jay and the core MODx Team are discussing what to do about the third-party add-on docs for MODx; but at the moment I personally think all documentation should be kept in the same place; easier for us and easier for our clients. It seems the new Confluence System would be powerful enough to handle a larger number of documentation pages; so as long as we organise all the information; making sure its clear if a piece of documentation is core or third-party we should be fine.

Bearing that in mind, one thing that does occur to me keeping the documentation simple and keeping it clear; it might not be the best idea to add every single item in the Extras repository to the new Confluence System, but then were could their documentation go?

So what’s everybody else’s opinion on this?

Well volunteered
I think quite a few of the repository items are pretty much dead, but it’s a difficult call on which.
What about all the links to the existing doc’s from the forum etc.?
The more I think about it, the happier I am that you’re doing it!
If you need some help let me know

@Adam,

so its not a simple copy-and-paste job; it took me over an hour to get the new AjaxSearch docs to where they are now by doing it manually;

Has anybody got any ideas for a quicker way to transfer the information to the new system?

The first thing may be is to ask (again) to the snippet developers, if they have the documentation available in a format different of the wiki. Which is my case. This could facilitate the documentation transfer.

Thanks a lot for the transfer of the ajaxSearch documentation from the wiki to confluence.
But what’s happens for the wiki documentation now ? Is the wiki page removed ?

We are going to have further discussions on the old wiki since there are no published links to it on the MODx CMS site at all.

My personal (meaning not necessarily that of the MODx team) is that all documentation should live in one of two places. A sanctioned single wiki (Confluence Wiki) or the developer’s personal site.

The media wiki site was underutilized and at the time it was implemented there was a mishmash of docs in the official docs (on the old MODx site) and everywhere else.

The #1 complaint of new (and existing) MODx users is that docs are too scattered and incomplete. As people start to use the Confluence Wiki and add or move 3rd party documentation there it will make for a better more informed user base.

Again, these are not the opinions of the MODx Team but my own.

Please share your thoughts.

Adam, I love the idea of consolidating the docs/wiki in one place. I find myself going to the old wiki first when I am looking for information and missing some of the great info in the ’new’ docs. I do this out of habit and not based on any bias.

If I recall correctly, one of the problems was that the official docs were not going to be open to public posting which would not make it a wiki but rather an official ’manual’ maintained or managed by the official team, and this was the reason that the wiki was kept active. Is this still the case?

I think it is nice to have 3rd party docs in a centralized wiki location rather than on personal sites. The main reason being that some developers disappear and their docs go with them, whereas if the docs were on a wiki or consolidated location the developers could move on but the docs would remain as a resource to others (also relieves the developer of the responsability of maintaining a site for the resource documentation). As well as making it easier to find docs for add-ons. And finally to make it easy to update and extend the documentation by the actual user base rather than being dependent on the developer to do so.

In any case I think it is great to have thought going into the MODx documentation issue

I would like to help too.

Moving all documentation to a single place is good idea.

As a side note, will it be possible for to upgrade the theme of the confluence wiki for more usability?
I think that a theme like this one would be more effective:

http://ffeathers.wordpress.com/2009/12/12/new-documentation-theme-for-confluence-wiki/

First some remarks
The first message of the home page of confluence is:

These Add-Ons are not officially supported by MODx, nor is their representative documentation. If you would like more info or help on them, please contact their respective authors.

And when you look at the documentation pages, no mention of the add-on authors. Except the name of the editors (Shaun and Adam) of the documentation in the page infos. Ok, I understand, this is the first draft of the documentation ...

It might not be the best idea to add every single item in the Extras repository to the new Confluence System, but then were could their documentation go?

Good question.
What will be the criterion to decide if the documentation of an add-on could/should be in confluence or not ? What will be the process of selection ...
All add-ons are outside of MODx, but are they some preferred add-ons ? ... I open the discussion too ...

Quote from: coroico at Dec 14, 2009, 03:47 PM

Good question.
But what will be the criterion to decide if the documentation of an add-on could/should be in confluence or not ? What will be the process of selection ...
All add-ons are outside of MODx, but are there some preferred add-ons ? ... I open the discussion too ...

At least, most of the existing doc should be transferred and then,(if the team agreed) maybe the documentation can be supplied by the developper at the same time he give his extension to the package repository.

Most of the wordpress add-ons are listed on the wordpress website with documentations, tutorials and related links if necessary.
This should not be a matter of preference but good practice.

On another note my preference would be for it to be split between Evolution & Revolution.

Thank you for the feedback on this ultra critical area. Maybe 2010 will finally see the "MODx is great, but the documentation sucks..." go away! Adam, thanks so much for taking the initiative on this.