next »

[dev_cw]

I still wish it was easier to figure out how to use custom Snippet calls: I always have this feeling that there are so many cool options with Snippets that are hidden from me. Maybe the new documentation will expand on this area?

I know the feeling. However, the more you use the snippets the more things become clear.

There are a few regular places to find documentation, this is where I look (in this order):

1) inside the actual snippet, most snippets have at least basic documentation right in the snippet code;
2) in the assets/snippets/snippetname/docs (or some variation);
3) Forum and Wiki or mini-site (like with Ditto);

The thing is that there is no real rule, some have it in one place while others will have different versions spread out through all the above. One example is Wayfinder that ships with docs for version 1.0, has great documentation in the MuddyDogPaws site but not 100% up-to-date, and has an unofficial full version 2 docs in the wiki as a download (which is greatly overlooked...I just noticed it the other day). Depending on where you look you will have a different understanding of the scope of Wayfinder...this is very confusing specially for newcomers.

Therefore my tip is to never think you have read it all, it is always a good idea to check in a few more places before being sure that you have seen all the docs. 

[cfn]

My idea was to write a A to Z diary of how to create a site with MODx. Start with a rough pencil sketch of the site and list the dynamic needs etc. Then a quick review of how to create the design in Photoshop, setting the dimensions and slicing up the graphics. Then comes creating a basic HTML template and getting the CSS down (using the graphics.) Then comes the MODx part: quick review of the install (easiest part) and then creating the foundation MODx Template. After that comes creating a menu dynamically and a review of the Manager and how to edit pages. Then the critical part: adding the various Snippets to make the site function. This is the area where most new users get lost, confused and frustrated (like me). Include a review of the most common and useful MODx Snippets that included details on what they do, how to install them and how to get them to behave. A list of the most useful Snippet calls for each Snippet would be great as well. I think a menu of Snippets for the most common type of dynamic sites would be useful. So, you could say "if you are building a community site with multiple web user bloggers you need the following snippets..." or "if you are building a brochure site with e-commerce you need the following snippets..." and so on. Showing graphics that indicate how the all the options and snippet calls works would be great as well. This would be a major task but if you had someone who knew MODx well and new how to communicate to users in ENGLISH then I think such a diary/tutorial would be most welcome. Not sure if that person is me but the idea is buzzing around that empty space between my ears.

Videos are awesome as well. I was confused with all the geeky lingo on getting PHP and MySQL running on my Mac and then a I found an online video: the guy walked you through it SLOWLY and you could SEE every step he did. I watched it twice and after that it was easy...

The online documentation lists all the features of MODx and explains the Editor pretty well. What is lacking is a well written guide that would explain to new users how to approach MODx from the install onwards. What's all that stuff in the MODx folder? Where does your HTML files go? Were do you put your CSS? How do you plan and implement the dynamic content? This is why a new Beginners Guide would make sense: these new user "crises" questions would not have to fielded as often...

STEP BY STEP TUTORIAL

A great TUTORIAL would cover most of these steps: creating a "project" for the most common type of dynamic website. The tutorial would build a full featured example site from scratch: well worded set that covers step by step instructions on installing MODx, setting up a site hierarchy, establishing Templates, Snippets, Chunks, adding HTML, adding CSS to build a starting HOME page. Written in straight forward ENGLISH. Often tutorials assume users know programming or the special terms involved. Then move on to step by step instructions for adding new pages while introducing Template Variables. Pictures illustrating the steps along the way would be great. Then introduce some added Snippets; for instance downloading, installing, and using MaxiGallery and eForm (all demonstrating actual samples). Then include procedures on backing up your work. Then show how to use the Editor and upload text, files and images. Maybe walk through all the steps involved in creating eCommerce and Forms etc, etc, etc.  <Obviously a MODx tutorial is not the place to teach XHTML and CSS.>

I see a TROUBLE SHOOTING Guide as a big plus. Maybe list common errors, error codes, Snippet call mistakes, caching problems, browser issues, operating system differences etc and what to do about them.

I know this would be a big undertaking. But having this kind of "blank page to finished novel" guide would go a long way of gaining traction for MODx and eliminate much of the "how do I get this to work" frustration that new users go through when installing MODx. Overall I find some of the documentation is useful. But some of it is very inconsistant when viewed from a new user point of view. This is true of many computer system instructions: some instructions are very detailed and others zip through critical steps: like having detailed instructions on how to open your vehicle's hood and prop it up but then saying "once the hood has been opened and secured you then change the engine..."

Max,

This was a good idea when you first wrote about it last December and still is now.   Lots of well organized thought went into your post, this is a great framework or foundation for some of that work to begin. 

Sort of like, we've developed this great system, we've organically talked about it, expanded it, and developed all this information about it....  now lets ORGANIZE the information so that a new group of people who are ready can start to use it efficiently and effectively. 

(And, forego having to reinvent any wheels along the way.)

The forums here are great, but as Max said, we have so many excellent and advanced developers that newbies if they're not tenacious sure can get lost, kind of like sending a 3rd grader into a huge college or law school library. 

One thought:  with the work that would be required to elucidate this, it could be a book.  Maybe a free e-book download and a purchasable hard copy so the writers get something for their time?  There are many co-writing/collaborating portals out there on the web, maybe some of us could get together and start something. 

The Wiki is great and certainly a great achievement, but, this would be an even higher level of organizing this information.  And I think video would be an even more cool/new/different way of decanting the information and getting it out there. 

Let me know if you need any help. I can read through your lists etc. It might be advantageous to have someone read it through the eyes of green newby (like myself...)

I recently signed on as an independent contractor for a tech services firm: building brochure sites for their clients. One of the things I am working on is creating a FAQ & Questionnaire White Page that will help clients pinpoint and list their requirements/preferences for what they want from their websites. Helping folks identify these areas goes a long way to creating the building blocks required for getting the sites completed efficiently.

Max

Max, I understand if what you developed is proprietary, but if you're willing or able to share, I'd certainly love to give that a read!  And probably make some changes to make it my own and use with my clients.  I agree with you completely that the intake process is a keystone to success.


The last comment I have to make, and it won't be a popular one, is that the Nucleus CMS I used to use seemed to be really easy for a beginner like me to grasp.  Now I want to do more, and have more options, so I'm beginning my journey with MODx.  But, I wouldn't hesitate to recommend Nucleus to anyone who feels that MODx is a little over their head and too much to grasp at the moment.  They have a great group of people on their forums as well.  Someone might come across this post and that might be the perfect answer for them at this time. 


Excellent topic!

John

[smashingred]

John,

Those are some great comments about Max's OP. I think that if someone wants to write about MODx or write How tos that would be apprecitated.

You will see over the next months and year that there will be many changes to the way information on the MODxcms site is presented. You will see improved documentation, more tutorials and less clutter. In addition there is a bit of an effort afoot to write a book with some of the team but others could be encouraged to do their own.

I had thought about working on a book on MODx but I realize that I need to help out with others as well I need to put food on the table today so I leave it for a bit. I am hoping to do some screencasts for newbs if I have some time in the next weeks as I have some projects winding down and a couple more sane projects starting.

If you have suggestions as to how information for newbs could be better presented please feel free to let the team know.

Sincerely and all the best,

Jay

[cfn]

Thanks, Jay,


I'm warmed by your response and happy to see that the team acknowledges and is aware there's a need there.  That's refreshing.


I used to be a teacher, and I work with a website client who used to be a teacher.  So, we talk about things like this, and, I would say an excellent guiding principle would be, when writing documentation, "How would I explain this to an eighth grader."


The more amusing thing is, when I work with older clients, who have established businesses but are getting on the internet for the first time, when I explain concepts and needs and options to them, I have to take it even a step further, and I have to use the principle of "How would I explain this to a fourth grader who I really love."  That implies all the wishes and hopes we have for the person and for their success and understanding.  And when I do that, its appreciated, so very much. 


Glad to be in touch with you. 


John

[Photowebmax]

Hi John,

Its interesting that this old thread of mine got found again.

I am very much with you on your thoughts and input on the documentation for MODx. I keep playing with it and then go back to what I know: static pages driven by CSS. And then I come back, only to realize that there are big gaps in my working knowledge of MODx, PHP and scripting languages etc.

I think wishing for a "magic" documentation that will make setting up and customizing a complex site built on MODx might always be just out of reach somehow. I feel that this is not the fault of MODX or the developers involved, rather it has more to do with the power of the MODx framework itself...

MODx is a foundation for building dynamic sites. Its power is in its adaptability: sure you can download the base install and start adding custom snippets like any other CMS out there. You can also build your own site with your own design and CSS system and pour it into the MODx framework. There are so many ways of doing things. Thats the power of MODx. But how best to illustrate that power and get users to show others why its a great tool?

The best way of getting used to MODx is to spend time with it. Creating several local test sites at the same time really pays dividends in learning the system.

What I still struggle with is the whole concept of bending the system and the snippets to make it work for specific site features. I will follow questions posted on this forum on "how to do this" and "why cant I do that", and I am amazed at the responses from folks like Susan or Doze etc: how do they come up with this stuff?  Folks like these seem to casually throw out code and custom snippet calls to make stuff work. To me this is where I wish there was a "how to guide". Installing MODx and getting it running is already covered. But how do you make the individual pieces of MODX sing like a Choir? How do select from the wide range of MODx features and custom snippets to create a great site feature set?

What I would love to see is a tour of tutorial sample sites that demonstrate how it all comes together for a set of robust dynamic sites that really capture the cutting edge power of MODx.

The geeks get it. Well good for them. But there are tons of creative designers who don't have the geek tools or mindset. They want to create not code! I still see MODx as a CMS framework system that is waiting in the wings, ready to explode... If it can be demonstrated to the creative designers, pixel pushers and and those who find all of the other CMS offerings too limiting in their tight structure requirements. Maybe the new version of MODx and the documentation that will follow will become this watershed moment? But like you say John, it needs to be explained and demonstrated in such a way that it will capture the minds, imagination and hearts of the many "seekers" out there who are so ready to embrace the next best tool...

Max

[markg]

Max,

like many others I share your thoughts. There are many posts throughout the forums pretty much covering the same theme "lack of decent documentation and requests for basic help"

There is, however,  a great deal of help and gems buried within the forums, but as you've noted you have to trawl through it.

I've resorted to reading from start to finish any post and thread that is close to what I'm trying to figure out. Usually there will be something buried in there that's what I need, but it's a time consuming and tedious process. Sometimes covering dozens of pages.

What we need is some way of taking all those buried nuggets and putting them somewhere that's cohesive and organised. I don't think the wiki is the  way to do it, at least not in it's current state. And books are always outdated before they are even printed. Anyone got any other suggestions on how the rest of us can contribute to some group developed documentation area or site? Given we are all in the online world some sort of dynamic documentation should be possible.

The other thing to realise is that people have different learning styles.

Telling people to read the documentation is only to going to work for a quarter of the population. The other 75%  will need something else.

Such as visuals and graphics. "A picture is worth a thousand words" Often one good graphic can communicate in an instant more than a thousand word tute ever could.

Other people need examples, or just need to see something working to get it.

EG Telling people battling with Wayfinder to "Just install the "accordion" example from the wiki or one of Muddydogpaws examples and you'll get it, " is not going to work if they can't get them to work in the first place.

[BobRay]

The geeks get it. Well good for them. But there are tons of creative designers who don't have the geek tools or mindset. They want to create not code! I still see MODx as a CMS framework system that is waiting in the wings, ready to explode... If it can be demonstrated to the creative designers, pixel pushers and and those who find all of the other CMS offerings too limiting in their tight structure requirements. Maybe the new version of MODx and the documentation that will follow will become this watershed moment? But like you say John, it needs to be explained and demonstrated in such a way that it will capture the minds, imagination and hearts of the many "seekers" out there who are so ready to embrace next best tool...

After spending a fair amount of time pondering this recurring question, I sometimes wonder if it's even possible. As you say, for those of us with a strong background in programming, it seems obvious how to toss off a custom snippet or make use of TV's, @bindings, and the programmatic hooks built into MODx to get what we want.  Unfortunately, even the most carefully written tutorial will only help users solve a limited set of problems and can't give them that programming background or the necessary way of thinking about the problem.

From reading this forum, I've come to see that many, many folks have needs that require custom programming to achieve. No generic tutorial or explanation is likely to help them very much. Certainly good beginner tutorials on Ditto, Wayfinder, Personalize, MaxiGallery, eForm, WebLogin, etc. will help get people going, but it's pretty hard to reach that next level without not only a desire to become a programmer, but a real love of doing it.

In a lot of cases, it might be a more satisfying solution to team up with someone who already has the skills. I, for example, love solving web site problems with programmatic solutions. I also enjoy designing the structure and navigation of a web site. When it comes to visual design, SEO, and .CSS, however, I barely scrape by and I don't really enjoy the work. One of my web sites has great custom programming, but I've been meaning to spruce up the menu for over a year now (it still uses the default Wayfinder menu with no tpl at all). Several of my sites desparately need SEO work, but I keep putting it off. Teaming up with someone who loved visual design, SEO, and .CSS and excelled at them would make my web work that much more satisfying and, as a bonus, more productive.

Bob

[Photowebmax]

Great post Bob! As always...

I guess its like wanting the best Swiss Army Knife but avoiding the instructions that explain how to open all the tools etc...

I am a pixel pusher. I have been a professional photographer for years but also like design. I like hardware and cool software. I like Macs.

I also have evolved into a web designer as a result of the transition from wet darkroom to Photoshop. I like CSS...

But there always seems to be this divide between the "design" world and the developer "geek" world. Please don't take my use of the word "geek" in a negative light. I am in awe of the skills and coding knowledge that these developers and code jockeys possess. In short I am envious and I use the term in a positive manner.

Design studios and web firms have the luxury of offering and using different people with different skills. Its rare to find a single person who has equal skills in both the design and developer coding worlds. But a lot of folks aspire to wanting to don all these "hats" at the same time. I am one of them.

But who can be a proficient pro at Photoshop, Illustrator, design, typography, color, layout, XHTML, CSS, CEO, Flash, PHP, MYSQL, Ajax, Javascript, browser issues, and CMS systems etc? Its really hard...

But quite often I am amazed at the skills of the developer as I am envious of the skills I do not have. What is also interesting is going to the sites that  these smart people have and often finding them so lacking from a presentation and design standpoint. Which just gets back to your valid point Bob...

But the nitty gritty is that I for one feel that MODx could be the magic bullet that a lot of the design world has been waiting for: it has the power and flexibility to make the personal vision shine.

With this in mind I am eagerly waiting for the new versions of MODx and other developments that these smart developer folks will come up with...

Max

[markg]

I think it would be a great shame and huge missed opportunity if MODx became a programmers' only domain. There are plenty of those type of solutions already, and they never make the next step up.

I think what attracts non programmers to MODx is its flexibility. We've tried other cms (in my case hundreds) and have eventually been frustrated with their inflexibility in certain areas.

We intuitively grasp that MODx holds the promise of something better. That it could be "the one" that makes all the difference.

As for the tutorials, many of the complaints are simply about getting started and getting things to work. We don't need custom programming, we just need clearer instructions (as per my previous post.)

The other area where I think confusion arises is that many engineers and programmers (in general) have a tendency to overcomplicate things. (Please don't take this personally, it's just a general observation.)

In that, regard programmers probably aren't the best people to be writing the tutes or the documentation. These should be written by people who understand human learning and communication.

EG: When people say they want more documentation, what they really mean is they want documentation that better explains what's going on. It may not necessarily involve writing more words, just better words or graphics, diagrams and pics.

Many of my queries on this site have been answered in two short sentences.

There is another alternative that has been suggested by others, and that is to simply turn on something like Camstasia or screen cam and record how you do things and what you do. Then post it as a common av file, podcast even.

Just seeing how something is done can make all the difference.

Once we all make it to base camp, then we can talk about custom programming, if it's even necessary.

For many of us a basic install of MODx with everything working is probably CMS heaven.

[ChuckTrukk]

It took me about 6 months, on and off again, to figure out MODx. And doing anything new in MODx almost always takes a learning curve- Jot, Wayfinder, Ditto, etc.

Documentation is so difficult because setting up (Ditto or Wayfiner or Jot) is a multi-step solution- where one mis-typed ` can make it not work. Then many of us know to check the cache, check for missing backticks, etc. I also think part of the 'problem' is the devs have really pushed the 096 core to its limits and suffer from old etomite terminology.

I think it does take a while to get the 'gist of it'. But once you do, you'll save so much time in the long run. But it really does take time to become unshackled from the normal CMS procedure and boxiness. I tell everyone to do a few things to begin MODx:
- install 2 sites (one with the default content and one blank)
- add your template for the base site. Put MODx calls in it.
- add a second page
- replace your current menu with Wayfinder. Make Wayfinder work the way you want with your current template. Do a View-Source to see if it works right.
- replace the content of your site with [*content*]
- repeat the Wayfinder steps to learn eForm or Ditto (I think eForm would be easier)
- add one text TV and place it one of your pages.
   - once you figure that out, try a TV with delimited list output (the widget stuff drove me crazy at first. I think a better explanation of this would help a lot of people.)

The above all takes time. You may need to let it rest a little bit and come back in a week. The key to me is:
- with Joomla, the module or component creates ALL html output
- MODx creates puzzle pieces (placeholders) that you can control every aspect of the html output (ie links, classes in Wayfinder or report form in eForm)

The wiki has made things 100 times better from when I first started this process. But documentation is the toughest thing for growing software. I think it takes (1) working through your site, (2) going step-by-step with the wiki tutorials, and (3) time to understand how chunks, snippets, tvs, and placeholders work.

Mark, how would you describe the following to an eighth grader:
- chunk
- placeholder
- Template Variable (which is a placeholder)
- snippet
- and how they work together?

[ChuckTrukk]

My try at explaining:
- placeholder
- Template Variable (which is a placeholder)
- chunk
- snippet
- and how they work together?


Placeholder
Placeholders are like dynamic pieces of a website. In Joomla, you may have a module that says "Hello username" where username is the logged in persons username. But in Joomla, you have no control of the output without hacking the actual php. In MODx, you can create your html output however you want and use a placeholder as the 'puzzle-piece'. 2 Examples:

Code:

//Example 1
<h1>Hello [+username+]</h1>

//Example 2
<div class="welcome-user">Hello <span>[+username+]</div>

The power of the above code is you did not have to 'hack' or modify the php that creates the placeholder. Most website clients want a unique and customized look to their site. Placeholders allow developers to create dynamic output (username) but allow you the designer to control the html and how it looks. Placeholders are usually put in 'chunks' (explained later). Most snippets document the placeholders available. When you first use a snippet, you may want to use all of the available placeholders to see what is available to you.

Template Variable (ie TV)
TV's are two things. (1) They are placeholders. (2) They are extra input options. The problems with CMS' like Joomla is sometimes your user needs more than 1 content field. What if the site owner needs 3 fields- Author, Web Link to Amazon, and email. In Joomla, the user could put that information in the 1 content box and format it the way they want. Or you could teach the user how to format the information the way they want (it's a hassle to show most people how to create a table or nested div with TinyMCE). But the power of MODx is you can create additional TV's (or input boxes). How to style the output (examples below):

Code:

//Example 1
<h1>[*author*]</h1>
<p>Web Site: [*website*]</p>
<p>Email: [*email*]</p>

//Example 2
<table class="books">
<tr>
<th>Author</th>
<th>Website</th>
<th>Email</th>
</tr>
<tr>
<td class="author">[*author*]</td>
<td class="website">[*website*]</td>
<td class="email">[*email*]</td>
</tr>
</table>

The power in the above code is the user does not have to know any of the html code. They just fill in their separate input text boxes, and the TVs are placed in their placeholders. TV's offer a lot of extra options, but this is the basics.

Chunk
A chunk is html that will be shown in a document. There are many reasons to place the html output somewhere other than the main content box. 1 reason would be html that will be used in multiple pages (like a menu, header, or footer). Another reason would be to use placeholders. If we use the above example, you could put that html in a chunk so the user could not edit it and mess up the table. Let's create a new chunk called 'Books' and call it to be shown in the main content.

Code:

<!-- New chunk called Books -->
<table class="books">
<tr>
<th>Author</th>
<th>Website</th>
<th>Email</th>
</tr>
<tr>
<td class="author">[*author*]</td>
<td class="website">[*website*]</td>
<td class="email">[*email*]</td>
</tr>
</table>

Code:

<!-- in the main content of MODx, show the above chunk 'Books' -->
{{Books}}

Now the user only sees the chunk {{Books}}, but the html output is the table we created that is populated with the TV placeholders. And if the user wants to add an image or more description above or below the 'Books' chunk, they can.

Snippet
A snippet is a piece of php code that creates the dynamic part of a placeholder. If we use the first example above, the snippet would be responsible for getting the username of the user and sending that to the placeholder [+username+]. In MODx, snippets are php functions and classes. They are what make MODx dynamic. I dont know what else to put here, because snippets can be anything you can think of. They are like modules or components in Joomla.

How it all works together
(1) Snippets do the php magic- calculations, query the database, massage data. They send the final output to placeholders.
(2) Chunks hold html output. You can call your placeholders here.
(3) Placeholders are where the output will be shown
(4) TV's are simple placeholders. They also provide simple input forms (in the manager) when you just need more input boxes.


Rough draft one - chunk
PS - will anyone actually read this if it's posted to the wiki, etc?

[markg]

Pro,

Mark, how would you describe the following to an eighth grader:
- chunk
- placeholder
- Template Variable (which is a placeholder)
- snippet
- and how they work together?

I would use diagrams, pictures and lots of coloured crayons, but not too many words.

Seriously, I used to teach uni students and adults accelerated learning skills and this is one of the types of methods we used.

Actually, I was hoping the eighth grader could teach me.

[ganeshXL]

hmm, actually, I think the Books-example chunk is a bit misleading.

Syntax for placeholder = [+foo+]
Syntax for template variable = [*foo*]

The example should be:

Code:

<td class="author">[*author*]</td>
<td class="website">[*website*]</td>
<td class="email">[*email*]</td>

[ChuckTrukk]

thanks ganesh,

i fixed it. That could be a source of confusion- TVs are called [*tvhere*] and placeholders are called [+placeholderhere+], but i guess thats just something people have to figure out.

[cfn]

This is generating some great discussion and ProWebscape, I would read what you wrote.  Its exactly the kind of thing someone like me would be looking for.

There is, however,  a great deal of help and gems buried within the forums, but as you've noted you have to trawl through it.

I've resorted to reading from start to finish any post and thread that is close to what I'm trying to figure out. Usually there will be something buried in there that's what I need, but it's a time consuming and tedious process. Sometimes covering dozens of pages.

What we need is some way of taking all those buried nuggets and putting them somewhere that's cohesive and organised. I don't think the wiki is the  way to do it, at least not in it's current state. And books are always outdated before they are even printed. Anyone got any other suggestions on how the rest of us can contribute to some group developed documentation area or site? Given we are all in the online world some sort of dynamic documentation should be possible.

The other thing to realise is that people have different learning styles.

Telling people to read the documentation is only to going to work for a quarter of the population. The other 75%  will need something else.

Such as visuals and graphics. "A picture is worth a thousand words" Often one good graphic can communicate in an instant more than a thousand word tute ever could.

Other people need examples, or just need to see something working to get it.

EG Telling people battling with Wayfinder to "Just install the "accordion" example from the wiki or one of Muddydogpaws examples and you'll get it, " is not going to work if they can't get them to work in the first place.

Mark, you're right on with all of this.  Really totally on track with it.


I want to suggest something for this question.  Not that I necessarily have the right answer or best answer, but, lets see where it goes.

What we need is some way of taking all those buried nuggets and putting them somewhere that's cohesive and organised. I don't think the wiki is the  way to do it, at least not in it's current state. And books are always outdated before they are even printed. Anyone got any other suggestions on how the rest of us can contribute to some group developed documentation area or site?

1)  I'd like to gather a team of people who would like to be part of writing/organizing the new docs.


2)  I think the first decision would be what kind of framework to use.  Maybe a new wiki.  I think the wiki we have now is great - but - I think we need a clean sheet of paper.  I would bet that a high percentage of whats on the current wiki would come over to the new one, but maybe in a different form or order.  It would be easiest to start with something new.  Whatever framework we use, even if it is a wiki, it would have to support videos and screenshots.  I think some kind of existing platform that uses rich text would be the best choice, I mean, we don't want to have to reinvent the wheel with that, we need something stable and intuitive so our work is easier.   Navigation and table of contents/sitemap/index kind of functions are key.


3)  This is an idea I got from the CouchSurfing group.  (I haven't couchsurfed anywhere yet, but I like the idea.)  They have these "collaboratives" which are in-person meetings in some cool place, that last anywhere from a week to a month.  Its an intensive.  A small group of volunteers signs up to do them, and then they focus intently on whatever goal they have set out for the collaborative.  They do strategic planning for the website and the community. 


I'm not suggesting an in-person intensive, although god knows, if we all had the resources (time and money) to meet that way, it would be a blast.  What I'm suggesting is lets each work from where we are, but lets maybe pick a period of time, say, (this is off the top of my head) the first 2 weeks of July.  And during those 2 weeks whoever is interested would just get as much done on the new docs as possible.  We would have a common goal and a "due date" to focus on.  It would have to start with an online chat or conference call where the basic parameters of the project and roles would be set out.  It would be some work for sure, but, it would undoubtedly get results. 


Again I'm not suggesting anyone put aside their lives for this - just if one is interested, they can set their own limits about how much time they want to give.  But, if I can be of help by organizing, or guiding, or editing... thats probably how I could best be of service to this project.


Is this a good idea?  Is it practical?


John

[OpenGeek]

John:

These are all desires of the MODx Team, and great ideas.  Let's see if we can't get all you folks that want to help improve the documentation for MODx involved in the official contribution channels...

1)  I'd like to gather a team of people who would like to be part of writing/organizing the new docs.

This is the purpose of the MODx Team, though the documentation group has been less active than we would like for sure.  If you have things to contribute, please solicit us to join the MODx Team, and you can spend as much time as you want/can helping out.  We ask people to join when we have time, typically after noticing some quality contributions from the forums and/or the community wiki, but don't be shy, please!  We need contributors.

2)  I think the first decision would be what kind of framework to use.  Maybe a new wiki.  I think the wiki we have now is great - but - I think we need a clean sheet of paper.  I would bet that a high percentage of whats on the current wiki would come over to the new one, but maybe in a different form or order.  It would be easiest to start with something new.  Whatever framework we use, even if it is a wiki, it would have to support videos and screenshots.  I think some kind of existing platform that uses rich text would be the best choice, I mean, we don't want to have to reinvent the wheel with that, we need something stable and intuitive so our work is easier.   Navigation and table of contents/sitemap/index kind of functions are key.

MODx development and documentation is being supported by a new full stack of Atlassian tools, which includes JIRA for bug tracking, a Confluence wiki, as well as Fisheye for Subversion Changeset viewing and Crucible for Peer Code Reviews.  Sign up for an account at http://svn.modxcms.com/jira/ and start participating.  MODx Team members are provided access rights to contribute in various ways, be it Subversion commit rights, wiki publishing rights, or rights to moderate a code review in Crucible.

3)  This is an idea I got from the CouchSurfing group.  (I haven't couchsurfed anywhere yet, but I like the idea.)  They have these "collaboratives" which are in-person meetings in some cool place, that last anywhere from a week to a month.  Its an intensive.  A small group of volunteers signs up to do them, and then they focus intently on whatever goal they have set out for the collaborative.  They do strategic planning for the website and the community. 

I'm not suggesting an in-person intensive, although god knows, if we all had the resources (time and money) to meet that way, it would be a blast.  What I'm suggesting is lets each work from where we are, but lets maybe pick a period of time, say, (this is off the top of my head) the first 2 weeks of July.  And during those 2 weeks whoever is interested would just get as much done on the new docs as possible.  We would have a common goal and a "due date" to focus on.  It would have to start with an online chat or conference call where the basic parameters of the project and roles would be set out.  It would be some work for sure, but, it would undoubtedly get results. 

Again I'm not suggesting anyone put aside their lives for this - just if one is interested, they can set their own limits about how much time they want to give.  But, if I can be of help by organizing, or guiding, or editing... thats probably how I could best be of service to this project.

We'd love to eventually have meet-ups, but the primary goal for the MODx Team here is to craft documentation for the upcoming 0.9.7 release so it does not suffer from all the same issues out of the gate.  We just need more volunteers to get actively involved in the documentation efforts.  Hint, hint...

As far as 0.9.6 is concerned, the existing community wiki allows anyone, not just team members, to contribute tips, tricks and tutorials already.  With this in mind, I do not see the point in expending more core team effort on the legacy releases, but I'm certainly not going to resist any organized efforts to improve the community wiki for the legacy users that will be around for some time to come, even once 0.9.7 is released.

We have an IRC channel for intensive communications as well (join #modx at freenode), and the core team members typically communicate via instant messenger when questions or other collaboration is required.

Cheers,

Jason

[markg]

Jason,

if 0.9.7 is coming, then rewriting and coordinating the current documentation may well be a redundant exercise.

While I have been one of those critical of the lack of clear documentation for newbies, I have found the people in the forums to be very helpful with whatever dumb questions I ask. Plus It's been less than two weeks since I installed MODx and I've had most of my pressing questions answered.

Maybe we should just tell all newbies to ask their questions in the forums until the new version comes out. Any time frame on when that will be?

The other thing I've noticed is that most of my queries relate to the installation and basic setup of external modules, snippets and plugins contributed by others, and not MODx itself.  That implies that snippet developers could/ should spend a bit more effort on these instructions.

As far as the Documentation Team goes, I'm happy to help out there. In my day job I'm a business communications consultant (marketing, advertising, training etc) and I've been involved in ecommerce since 1998.  So if you want a writer's eye and communicator's insight to go over anything just pm me.

[cfn]

Sounds good Jason... so the new 0.9.7 will be basically a clean/fresh start for documentation.  That is great. 

So Mark is probably right that spending a lot of effort on the existing docs wouldn't be such a good idea, and we'll just all have to be patient in the interim.  I agree with Mark that forum users are incredibly supportive.  Without clearly navigable docs where the newbie questions and answers can easily be found, there's always the danger that newbies will be too intimidated to ask all the questions they wish to, that they'll give up if they're not tenacious, and that patience from the advanced forum users will wear thin.  That's known already, I'm sure, and with that statement I'm just repeating the need.

With the new docs, I'm willing to help too.  But... Jira and the other developer tools you mentioned... those don't interface with me very well.  Wikis, how-tos, and user docs in plain English is where I can be useful, but, looking at the extensive tools you have on the svn page gives me the same headache as a lot of the existing MODx docs.  If there's an official communication channel that is more on my level I'll be glad to participate any way I can.

I'm supportive but just don't know what kind of role you would want me to have.

One idea is that the more technically advanced team would have to do the initial writing.  But, they could hand their first draft docs over to a second team comprised of less technical writers/editors.  Then, after we work through it and rewrite and revise, we would have some discussions back and forth between the 2 teams, asking questions, clarifying, and so on.  It would almost be like an interview session, where we fill in any gaps of understanding that need to be filled or clarified.  And, then we could beta test the docs on people who are even less technically inclined than we are, such as business people or people just wanting to make a quick site. 

So, it would be a real team effort with contributions from people of all ability levels.

John

[splittingred]

With the new docs, I'm willing to help too.  But... Jira and the other developer tools you mentioned... those don't interface with me very well.  Wikis, how-tos, and user docs in plain English is where I can be useful, but, looking at the extensive tools you have on the svn page gives me the same headache as a lot of the existing MODx docs.

The Confluence Wiki is a pretty simple Wiki - I feel MediaWiki is much more difficult. You can find the 097 docs (in vast need of contributors!) at:
http://svn.modxcms.com/docs/display/MODx097/MODx+0.9.7

If there's an official communication channel that is more on my level I'll be glad to participate any way I can.

Most of us communicate either via these forms or in IRC at irc.freenode.net, on the channel #modx.

I'm supportive but just don't know what kind of role you would want me to have.

We want any contributors of documentation. We want testers and bug submitters for 0.9.7.

Thanks John.

-shaun

[smashingred]

Don't avoid adding documentation for 0.9.6 because while there is much different about 0.9.7 there is much the same or very similar.

Personally, I' plan to put up some screencasts and videos demonstrating how-tos in MODx.

Many people [claim they] don't get anything from screencasts but many of us do better with visual demonstrations, pictures, screencaps and flowcharts rather than text only documentation.

I have learned subjects from Acoustics to HTML to Graphic design to PHP using images, video and charts. Obviously notes, text documentation etc. is necessary but not isolated. The reason many people do mind mapping is that imagery can bring significant clarity to ones ideas and thoughts. WIkis are often devoid of valuable images and this is a shame. My favourite web design and programming books and even Tony Buzan's Ultimate Book of Mind Maps are jammed with demonstrative examples.

People make fun of the Ruby on Rails screencasts as a silly waste that shows nothing but what it did for me was give me insight into process, actions, format, syntax; a starting point. While I don't use RoR, one 10 minute video gave me way more insight into its use in application development than a 5page step-by-step howto becuse howtos don't have the dimension. A screencast can efficiently tie together several related elements all while concentrating on the one vs. constantly interrupting flow with "By the way while you do this you can...".

Anyway, Confluence is really easy to use and has an RTE that converts to wiki markup quite nicely and as splittingred mentions it is easier than Mediawiki markup; I'd agree.

Cheers,

Jay