Frustrated with Revolution Documentation

I know that I’m not great with the programming stuff. I’m a designer first who has struggled my way through using wordpress, joomla and modx. I’ve been using Modx evolution for a while now and I really do enjoy it. I finally feel like I can bang out a site and get most of what I want done without pulling out my hair. But, I’m now working on my first Revo site and for the most part it has gone well except now I need to learn new snippets and try to figure out how to do things all over. I expected this. It comes with the territory, but I have to say that the documentation that I have encountered has just been so hard to follow and understand. Everything that is written assumes you have a high level of understanding and expects you to just fill in the blanks. It’s becoming very frustrating. I think I had more luck in Evo because of how long it has been out. There are so many good tutorials done for designers and people who can’t program their way out of a wet sack. There just aren’t any good tutorials yet for Revo that break down things in an easy to follow, user friendly way. I need to learn Gallery, Formit, getResources, and on and on and what I’ve found so far just confuses the crap out of me.

I’m just venting a bit here. I’m sure things will get better.

I look forward to the new tutorials that are bound to be in the pipeline somewhere.

Again, love the software and the whole modx community. Just feeling a bit exhausted at starting over.

Don’t feel bad, a lot of people are in the same boat (myself included). Revo just recently made its first public release, and documentation is in the process of being overhauled. There is even a Revo book in the works. So things should shortly be much improved in this area.

Same here. Completely new to MODx, and I understand it’s a new version and it’s FOSS, but I shouldn’t have to search so many places to find answers (wiki, docs, forum, bugtracker, 3rd party sites), and see so many forum posts unanswered (especially mine ).

Well, I know it will get better. I think that the documentation that we’re dealing with now comes from the people who are creating the snippets, software, etc. They are intimately familiar with their software and the code base of Modx. Those of us who are designers need a more visual way of explaining things. Show me how it works. Follow the steps and explain it to me like I don’t know everything about the core code, the error logs and the history of updates and bug fixes.

I guess we just have to be patient. I jumped in to Revolution a bit too soon I believe. I had a project that I thought would make sense using the latest version but I just didn’t check out where it was before I jumped in. No front end editing yet? Wow, I guess I should have known that. It was always the biggest sell with Modx I just couldn’t imagine it not being in Revolution.

So, I guess it’s time to be patient and see how things progress.

Quote from: mdsdesign at Sep 14, 2010, 11:08 AM

Well, I know it will get better. I think that the documentation that we’re dealing with now comes from the people who are creating the snippets, software, etc. They are intimately familiar with their software and the code base of Modx. Those of us who are designers need a more visual way of explaining things. Show me how it works. Follow the steps and explain it to me like I don’t know everything about the core code, the error logs and the history of updates and bug fixes.

I guess we just have to be patient. I jumped in to Revolution a bit too soon I believe. I had a project that I thought would make sense using the latest version but I just didn’t check out where it was before I jumped in. No front end editing yet? Wow, I guess I should have known that. It was always the biggest sell with Modx I just couldn’t imagine it not being in Revolution.

So, I guess it’s time to be patient and see how things progress.

It looks like there is a front-end editor being developed: http://modxcms.com/forums/index.php/topic,53822.0/topicseen.html

You might also try the "Its All Text" Firefox addon.

Thanks Bob. This is all good news. I think I just jumped in a bit too quickly. It’s going to be amazing when everything is really rolling. But for now, but knowledge and comfort level with Evo probably makes more sense. Also, I use MaxiGallery and the front end editing for all of my client sites and they just work so well. So, until some of these features are standard in Revo, I’m going to hold off.

Looking forward to seeing Revo grow.

Front-End Editing isn’t a main focus for the Core Team because the Core Team should be working on the Core, not add-ons for it. Not everyone needs front-end editing, and therefore that makes it an Extra rather than a Core issue.

We’re at a point where the Core Team has to stop making Extras for the community, and the community needs to make Extras and share them itself. If this never happens, we’ll have a Core Team that is increasingly investing in maintaining and creating Extras, and never working on the Core - and the main product will never progress. We’ve spent a lot of time updating and improving the documentation (and will continue to do so), and are hoping that some people start picking up the torch with regards to Extras development. Also, our move to GitHub has allowed people to easily collaborate on Extras development, even if they don’t "own" the Extra.

In other words, an "Oh, Revo isn’t fully documented or ready; therefore, I’m not going to invest in it" is not the right attitude toward Revo. Evolution didn’t get where it is because the Core Team created all the things for it - the community stepped up and filled in the gaps. Revolution, like all open source projects, will live or die on community investment. We as a Core Team can only do so much.

We also understand that not everyone is a developer. I agree; the worst thing for a project is a bunch of Extras that don’t work well because they were written by non-programmers who were rushing to add something. However, I would posit that *everyone* can be a documentor. Often, developers make the worst documentors - we think too technically about systems, and often write more technical documentation rather than end-user focused docs. The best documentors are people who are trying to implement something that they didn’t write - because they have the exact same perspective that future readers of the documentation will have. So while I would agree wholeheartedly that Revo’s documentation isn’t fully fleshed out (nor are all the Extras’s docs, either), everyone simply saying it isn’t ready and walking away is a dangerous consumer mindset and doesn’t progress the project. In other words, "many hands make light work" - if we all contribute, we all benefit.

This is Open Source; you get what you give. Yes, Revo is young. Yes, the documentation is not fully fleshed out. But yes, no one is paying for this (except arguably the core team, who gives this away for free), and like any free product, you should expect that you end up spending your money in other, less direct avenues. You don’t pay a fee - but you’ll probably have to spend some extra time delving into the project or contributing back.

Thanks for your thoughts, and welcome to Revolution. Looking forward to your feedback in the future.

Thanks for your reply SplittingRed. Very well put and point well taken. I know that I will never be able to develop an add-on, but I certainly have figured out a lot of ways to do things and do believe I could explain some of the stuff that took me a while to figure out to new users.

So, that’s exactly what I’m going to do. Get more involved, help out where I can and look for the continued help that is out there.

You guys have done an amazing job with ModX and it just keeps getting better. Reminding us all that it’s up to all of us to move the product forward was important.

Thanks.