We launched new forums in March 2019—join us there. In a hurry for help with your website? Get Help Now!
    • 23299
    • 1,161 Posts
    Well, it is not a secret that MODx has less than stellar documentation. Its a fast moving system and even good information can become quickly outdated. At first I thought it would be great to have a complete "MODx Bible" that covers everything. Now I am not so sure.

    The best resource for absolute newbies, users, and developers is this forum. I think what folks want is an easy to digest "Cliff Notes" resource that helps them navigate forward. I find the members on this forum to very patient and helpful. There are a lot of talented people who are very much focused on the project. Many willingly part with their experience and knowledge.

    But...

    Sometimes there is a disconnect with the language and jargon they use when addressing newbie questions. I have followed threads that go on for two pages on the same stumbling block that I am battling with. Experienced users will point out that the solution is "to change the permissions for the blah, blah, blah..." The original poster then replies, "yes, that worked!" Great! But how did you do that!!!??? This is super frustrating. You then have to fire up the search engine again with the hope that this has been covered in better detail...

    One of the nice things with MODx is CHUNKS, small bits of code that can get used over and over again. I think it would be nice to take this idea and apply it to this forum. Say you are chatting about folder permissions and server issues. If you suggest changing 777 to 645 that might be crystal clear to a lot of folks. Its a bad assumption that everyone know what you are talking about though. The vast majority of issues or queries have been asked many times. It would be nice to build a "see this explanation" list of questions/problems/solutions. These would be helpful CHUNKS  in a way. So, if you are suggesting a user changes his 777 to 645 you then add a quick CHUNK link on how to actually perform the task. Those that know the concept don’t have to follow the link. Those who are thirsty for more detail can then quickly check out the link, learn, and then follow the discussion with greater understanding.  In the long run this would save a lot of time for everyone. The collective knowledge level of everyone could be raised as well. Its an idea anyway.

    Every question and response becomes part of this MODx forum’s archive. What gets said can be read over and over by countless people looking for answers. If people were more cognizant of this they might communicate a little more clearly. I for one find it very useful when posters provide links  to great discussions. Some archived technical threads are great and some are useless even though they ramble on for pages...

    Having a "Top Ten List" of all the major MODx components would be great: top ten questions, top ten solutions, top ten examples etc...

    Communicating Snippets: for me this is a biggie. I know that writing these snippets must take a ton of work. What I find strange sometimes is that what these snippets actually do for the end user remains murky. Going to the authors site sometimes will reveal a long history of each improvement. Great! But what does your gizmo actually do and why should I care? I am currently doing a site with custom photography for a client who is launching a new technology application idea. The text I was given was very vague and flowery. In the end I asked this guy: "think like a fresh viewer to your site. ’What is your product specifically and why should I care? You have twenty seconds’..." Smart people can make smart things. That alone does not guarantee success. Often it takes very clear descriptive communication that captures the imagination of the end user...

    Gotta run...

    Max
      • 3749
      • 24,544 Posts
      Quote from: ganeshXL at Feb 03, 2008, 05:18 PM

      Quote from: BobRay at Feb 01, 2008, 12:05 AM

      The biggest lack I’ve noticed is an explanation for beginners on how to use the various Tpl chunks to style snippet output (particularly Wayfinder, Ditto, and MaxiGallery). There’s really no place I could find that explains the basics of what things like rowTpl, innerTpl, outerTpl, etc. actually do.

      This really surprises me. I always thought that Kyle did an excellent job with his Wayfinder documentation: http://www.muddydogpaws.com/development/wayfinder/
      Every single parameter etc. is explained, he even posted 7 fully functional real-life examples where every tpl is shown. Also, the names are pretty much self-explanatory: outerTpl = outer template etc.


      I hadn’t seen that part of Kyle’s site. It’s much better than anything I’ve seen before (and beautifully designed).

      I think it might be improved by having a simpler example somewhere with a display of the final html output by the snippet. It would be especially cool if the parts contributed by the different tpls were color coded.

      Also, I have to point out that "outerTpl = outer template" might not actually mean anything to a MODx newbie and, although Kyle has done a great job with Ditto, there’s no general documentation on the use of tpls in MODx snippets that I know if. I remember spending a fair amount of time looking for it when I started out with MODx.

      Bob


      Bob
        Did I help you? Buy me a beer
        Get my Book: MODX:The Official Guide
        MODX info for everyone: http://bobsguides.com/modx.html
        My MODX Extras
        Bob's Guides is now hosted at A2 MODX Hosting
        • 22303 MODX Staff
        • 10,725 Posts
        Quote from: BobRay at Feb 03, 2008, 06:42 PM

        Also, I have to point out that "outerTpl = outer template" might not actually mean anything to a MODx newbie and, although Kyle has done a great job with Ditto, there’s no general documentation on the use of tpls in MODx snippets that I know if. I remember spending a fair amount of time looking for it when I started out with MODx.
        That’s a very good point, but I would say that there never will be general documentation that covers add-on specific features and functionality, like Wayfinder’s internal templating model is. It does not work the same as Ditto’s templating. And when I deploy sites on MODx, I’ve used a number of different techniques to solve the same problem myself, trying out each to find strengths and weaknesses. In this experience, we’ve collectively found strengths and weaknesses in the framework regarding the way add-ons handle internal templating needs, and likely found several new ways to do something else on the way. These in turn are directly affecting the development of future releases of the product. I think this is a healthy cycle that needs to be encourage and nurtured so that more developers can provide solutions targeted at less DIY-inclined end-users.

        An important point to keep in mind: Ditto and Wayfinder and whatever other snippets or techniques you adopt for use in your MODx site are user-contributed, and they do not define MODx. The development of these add-ons certainly helps to evolve the core framework, improving the way developers interact with it. But, MODx itself will never provide end-user targeted solutions directly to people who do not already have some level of knowledge of standard web development techniques. This is the core competency of MODx; enabling the deployment of user-maintainable web sites without sacrificing web standards.

        Some of the more popular add-ons that individuals have developed and contributed to the community, just like Ditto and Wayfinder, are included in the current release of MODx because, well, it is easier to have them installed and demonstrated in the sample site than give people pages of instructions on how to manually install all the add-ons the sample site uses. In fact, in the future, the main distribution of MODx will include nothing but the core, the setup interface, and the default manager interface.

        As a team and community, we specialize in providing a content management framework on which web designers and developers can collaboratively build sites to spec using accepted techniques and standards. And beyond that, we offer suggestions and assistance to each other as we use the framework to deploy and maintain our own or our clients’ sites. But MODx does not, and will not, prescribe add-ons or change focus to developing/supporting a specific component. MODx will not arbitrarily impose standards on users either, but will instead encourage the developer community to use competition and consensus to drive the creation of best practices that potentially could become standards where appropriate. There are simply too many ways to solve the same problem in MODx and saying that all snippets must provide a certain parameter to do it’s work just because another popular one was successful with the technique is not sufficient consensus to establish a standard upon.
          • 34017
          • 898 Posts
          Quote from: ganeshXL at Feb 03, 2008, 05:09 PM

          Something like an FAQ would make sense. Based on real-world examples and -usage.

          I see a lot of questions here that basically go "I want to make X. How would I do that with MODx?"

          Just a few quick examples:

          - How can I produce "news-teasers" on my frontpage?
          - How can I create an RSS feed of my blog-folder?
          - How can I build a dynamic sitemap / navigation?
          - How do I create "content blocks"?

          Each of these questions would feature a solid answer, quick examples, maybe screenshots, and links for further reading and perhaps "related topics". + Wiki links, forum posts... whatever. A tag cloud would help people find what they’re looking for.

          The new Beginners section in the wiki is meant for this (http://wiki.modxcms.com/index.php/Category:Beginners). I hope it can be a place we can explain the basics that most rookies can go to for simple examples and explanations. I have begun to put some tutorials from forum posts over there. If you have anymore, please feel them in at the wiki. I feel the wiki is one of the best documentation/infrastructure items the staff have setup since I started using MODx.
            Chuck the Trukk
            ProWebscape.com :: Nashville-WebDesign.com
            - - - - - - - -
            What are TV's? Here's some info below.
            http://modxcms.com/forums/index.php/topic,21081.msg159009.html#msg1590091
            http://modxcms.com/forums/index.php/topic,14957.msg97008.html#msg97008
            • 29525
            • 388 Posts
            Quote from: BobRay on Feb 01, 2008, 12:05 AM
            The biggest lack I’ve noticed is an explanation for beginners on how to use the various Tpl chunks to style snippet output (particularly Wayfinder, Ditto, and MaxiGallery). There’s really no place I could find that explains the basics of what things like rowTpl, innerTpl, outerTpl, etc. actually do.

            ----------

            I agree with BobRay. As a new MODx user, who is not a programmer, I find there is a lot of assumed knowledge here. I struggle with overall use of this information, big picture, how all the pieces fit together. For example, how do the parameter and chunks work together, where to do they go, etc.
              www.terrybarthdesign.com
              • 3642
              • 48 Posts
              Thanks for the suggestions. I have started putting together http://wiki.modxscrolls.com/index.php?title=Convert_template. I am about a third of the way through. I need to add screen shots to make it easier to follow. I am not trying to duplicate what is at wiki.modxcms.com. Instead, my goal is to put up less technical information, if that makes sense. Let me know if you think that I’m taking the wrong approach.
                Michael Henderson
                MODxCMS + Dreamhost P/S + BBEdit
                Safari + Mac OS X 10.8
                • 3749
                • 24,544 Posts
                Quote from: BlueRonin at Feb 10, 2008, 01:58 PM

                Thanks for the suggestions. I have started putting together http://wiki.modxscrolls.com/index.php?title=Convert_template. I am about a third of the way through. I need to add screen shots to make it easier to follow. I am not trying to duplicate what is at wiki.modxcms.com. Instead, my goal is to put up less technical information, if that makes sense. Let me know if you think that I’m taking the wrong approach.

                @BlueRonin,

                Good start. smiley

                You might look here: http://bobsguides.com/porting-your-site-to-modx.html

                It’s not exactly what you’re trying to do but might give you some ideas.

                Bob
                  Did I help you? Buy me a beer
                  Get my Book: MODX:The Official Guide
                  MODX info for everyone: http://bobsguides.com/modx.html
                  My MODX Extras
                  Bob's Guides is now hosted at A2 MODX Hosting
                  • 27708 MODX Staff
                  • 2,502 Posts
                  Quote from: BlueRonin at Feb 10, 2008, 01:58 PM

                  Thanks for the suggestions. I have started putting together http://wiki.modxscrolls.com/index.php?title=Convert_template. I am about a third of the way through. I need to add screen shots to make it easier to follow. I am not trying to duplicate what is at wiki.modxcms.com. Instead, my goal is to put up less technical information, if that makes sense. Let me know if you think that I’m taking the wrong approach.

                  I like where you are headed with this. Sort of a "field guide" to MODx.

                  One criticism is that you should take advantage of headings and subheadings to break up sections and subsections on an individual page. Long blocks of text can easily be made easier to read if you paraphrase or offer a them for what will appear after a heading. It allows people to scan which is how people read online--scan to the section that sounds like what they want and read from that point.

                  Keep writing. The more voices about the use of MODx the better.

                  Cheers,

                  Jay
                    Author of zero books. Formerly of many strange things. Pairs well with meats. Conversations are magical experiences. He's dangerous around code but a markup magician. Blog ✦ Twitter ✦ LinkedIn ✦ GitHub
                    • 25663 MODX Staff
                    • 12,272 Posts
                    For anyone looking for a good screencast workflow in pursuit of the perfect documentation: http://www.37signals.com/svn/posts/775-ask-37signals-how-do-you-make-screencast-videos
                      Ryan Thrash, MODX Co-Founder
                      Follow me on Twitter at @rthrash or catch my occasional unofficial thoughts at thrash.me
                      • 3642
                      • 48 Posts
                      @Jay - Thanks for the comment. You’re right, breaking it up will make it easier to read. Right now it reads a lot like Moby Dick.

                      @Bob - I’ve already hit your site up a couple of times. I’ll add it to my links section. I’m debating how to use the wiki. My first thought was to use it to create a draft then, when I’m satisfied with it, convert it to content and stuff it into my main web site. Depends on if I can get MediaWiki to work well with my hosting company. It’s pretty sluggish right now.
                        Michael Henderson
                        MODxCMS + Dreamhost P/S + BBEdit
                        Safari + Mac OS X 10.8