Do we really need another space on the RTFM for 2.1?

Instead of putting everything in one place where people can find what they need easily, creating another space for 2.1 is only going to confuse end users more, and there’ll be duplicate information all over the place.

Wouldn’t it be better for a release like this to just go through the Revolution docs and highlight things depreciated in Revolution 2.1 and keeping that one space updated to the latest specs until the basics drastically change?


I’ve never been a fan of the way Confluence is set up, but it’s manageable until you start creating spaces for everything in there.. Ideally (well, imo anyway) there should be one for Evo (096 should just be depreciated imo), one for MODX Revolution and one for Evolution addons and one for Revolution addons.

Imo xPDO (although developed by the core team/Jason) should have its own wiki on the xPDO.org website, and the MODX Revolution space should have a section dedicated to the basic xPDO methods that can be used with a link to the xPDO docs where it is out of scope to discuss.

Furthermore...
- the DEV space has only a few pages and one of them still speaks about SVN which could do with an update. Or rather just delete that space, and add those to Revolution or Evolution depending on the page.
- The examples space is for MODX Revolution examples... so add it to the MODX Revolution space to keep it all in one place. I wouldn’t know how to find it unless I’d know it was there.
- The extension space only has a doc about Template Package which has been depreciated in favour of PackMan which is documented on the Addons space.. any reason to distinguish between extensions and addons? They both extend the core in one way or another. I’d vote to remove the extension space.

The Old Revo docs space gives a 302 response to http://rtfm.modx.com/display/revolution/MODx+Revolution which then seems to want to redirect somewhere. The old Revo docs still frequently show up on Google cause it’s not simply sending out a 301 to revolution20. If it was my call I’d put a .htaccess in place to simply redirect everything targeted at /display/revolution/* to the newer docs and delete the entire space.

That’d bring down the number of spaces to only a few and make it much more manageable and easy to use..

++ for moving MODx 0.9.6 away and keeping 2.1 and 2.0 in one place.

I’d like if the Evo Add-Ons moved outside of ADDON somewhere else. maybe everything should be structured like:

- Evolution 0.9 - 1.x
- Documentation
- Add-Ons
- MODx 0.9.6

- Community Information

- Revolution 2.x
- Documentation
- Add-Ons
- Examples
- Old Revo Docs
- xPDO

Quote from: Mark at Mar 29, 2011, 12:03 PM

Instead of putting everything in one place where people can find what they need easily, creating another space for 2.1 is only going to confuse end users more, and there’ll be duplicate information all over the place.
Wouldn’t it be better for a release like this to just go through the Revolution docs and highlight things depreciated in Revolution 2.1 and keeping that one space updated to the latest specs until the basics drastically change?

No, as the core base might drastically change, as well as relationships between objects. A great example for 2.1 is TVs - TVs add Input Options, as well as restructure how they are loaded (no longer by ajax). Also, the caching system for MODX is entirel different. modUser’s now use hashing and PBKDF2 for encryption. A *ton* of deprecated methods were removed.

And you think that’s different? Wait till 2.2 or 2.3 - when we introduce static elements, in-manager updating, custom dashboards, etc.

There *needs* to be separate documentation for each minor version of MODX; otherwise we’re shooting ourselves in the foot in terms of scalability. If a user can’t figure out that when they use 2.0.x, they should look at the 2.0 documentation, well - tbh, that’s not our fault.

- the DEV space has only a few pages and one of them still speaks about SVN which could do with an update. Or rather just delete that space, and add those to Revolution or Evolution depending on the page.

It has been removed; it was an old space and the Community space is more applicable now.

The examples space is for MODX Revolution examples... so add it to the MODX Revolution space to keep it all in one place. I wouldn’t know how to find it unless I’d know it was there.

It definitely needs to be reviewed.

The extension space only has a doc about Template Package which has been depreciated in favour of PackMan which is documented on the Addons space.. any reason to distinguish between extensions and addons? They both extend the core in one way or another. I’d vote to remove the extension space.

Agreed, removed.

The Old Revo docs space gives a 302 response to http://rtfm.modx.com/display/revolution/MODx+Revolution which then seems to want to redirect somewhere. The old Revo docs still frequently show up on Google cause it’s not simply sending out a 301 to revolution20. If it was my call I’d put a .htaccess in place to simply redirect everything targeted at /display/revolution/* to the newer docs and delete the entire space.

Yeah, Confluence makes this a bit tricky. We’ll look into it.

Thanks Shaun!

I still don’t agree on splitting things up based on minor version. I realize a lot of work has gone into it and a lot of things have changed, but in my opinion it makes more sense to put a box on top of a page, or at the start of a paragraph indicating anything specific was meant for Revolution 2.1 and up. Depreciated methods shouldn’t have been in the documentation to begin with and it wasn’t documented that TVs were loaded with Ajax anyway. Try typing in "template var" in the search box right now - there’s a stunning 5 pages with that name right now (096, evo, old revo docs, revo 2.0 and revo 2.1) with little to no difference in content on the last three pages...

At least in 2.1 most of the changes are behind the scenes and the average end user (if there’s even such a thing) wont even notice the way TVs are displayed, or how passwords are stored. Other changes they will notice, but I still believe a simple re-usable (so uniform looking) chunk at the top of a page or section would work better to differentiate between versions than a complete copy of what already exists. (Google & Duplicate content?).

I do understand you’re reasoning on the subject, but with probably over 95% of the documentation entries being the same I don’t see the benefit compared to simply putting a 2.1 or up tag.

Just to toss out a few more suggestions....

I think we should move the 0.9.6.x docs in with evolution, after all they are very similar, a few naming changes plus the TV change in 1.0.5, but that can be addressed in a 0.9.6.x vs 1.0.5 page saving space and avoiding confusion.

I STRONGLY agree with breaking up the Add-Ons to have Evolution and Revolution. I realize some addons are hybrid (MetaX for the most part), but going forward it will help to organize things. The two are separate and we are reinforcing this more on the main site, so it only makes sense to me...

Revolution Documentation - I agree with Shaun, we should maintain version specific documentation, but my suggestion would be to handle it differently. I would have a General Revolution area (great for examples, basics that don’t change, etc.) You can then have a page covering each version. I don’t know that a full area for each version, building a blog with Revolution is going to change between 2.0 and 2.1 is it? Sure, there may be benefits in later versions, but as noted those can be added inline.

Yes, there are drastic changes between 2.0 and 2.1, but are they enough to justify rebuilding an entire sections worth of documentation? If anything this will quickly lead to user confusion, and out of date documentation for older version IMO.

Just food for thought...

Looking down the road, I’m concerned about the complexity of having a new docs section for every major version. That works fine if you only have two or three versions, but not, IMO, when you’ve already subdivided things into Evo and Revo. I also worry about the time it will take to create and update the docs. We haven’t been able to keep the Evo and Revo docs accurate and up-to-date as it is, this will get worse, not better if we split out the major versions and have six or eight different sets of docs for Evo and the same number for Revo down the road.

I haven’t spent a lot of time looking at the the changes in 2.1.0, but so far, I don’t see them as requiring a whole new set of documentation -- and people should be upgrading regularly anyway, so where’s the harm in having one set of docs that match the current version.

I can see having the automatically generated PhpDocs stuff be version-specific, but IMO, it makes more sense for the hand-made docs to have one section for Evo, one section for Revo, and one section with some info on upgrading from one version of each to the next.

I totally agree with Mark and BobRay. Documentation is an important thing for MODX and for potential users. Many many beginners to MODX claim for better documentation and we try to improve that but if there are more and more new docus on the way for 1.0,1.1,1.2,1.3,1.4 / 2.0,2.1,2.2,2.3,2.4 / 3.0,3.1,3.2,3.3,3.5 - how far will this work?

It’s like the browser thing - users should update as soon as possible so browsers now provide auto-updates. If we support older versions by providing old docs but no new docs for each version we’ll shoot ourself?!

The MODX Core Team discussed this at length today, and we’ve decided the following:

1. We’ll move the documentation for 2.1 back into the 2.0 space; all documentation for 2.1 should be done in http://rtfm.modx.com/display/revolution20/ but with flags/childpages where differences from 2.0.x occur. We’ll have a spec document out soon on how to do that.
2. We’re eventually going to move away from Confluence in the next year, moving to a much more version-friendly format: Git. We’ll move all the documentation to Git, served up as webpages in MODX. Then, we’ll add the ability to edit via the front-end. This keeps the docs SSO, versionable per MODX version, and in a much more flexible format.

So, documentors, thanks for your feedback. It was invaluable during discussion. Keep on documenting!

Thanks.

Thanks guys for discussing this! Really appreciated you took the time to come to a proper solution.


(I just hope that’s not an april prank.. )

Quote from: Mark at Apr 01, 2011, 04:20 PM

(I just hope that’s not an april prank.. )

Oh no, if it was, we would have suggested doing the documentation in Lotus Notes.