Good pro-MODx arguments needed

Quote from: Maaike at Feb 07, 2008, 12:40 PM

I personally believe the best marketing tool for MODx would be better documentation. That way we could attract more designers and front-end developers (ummm... people like me), who currently find the learning curve a bit too steep. I mean, we have a great user base right now, but we want MODx to become more mainstream, right?

Yes. This is all in the works for 0.9.7. We’ll be using a new system for ticket reporting, SSO integration (so your bug reports, forum links, etc are all connected), PHPdoc documentation, and docbook documentation for everything. 097 is a major move forward on documentation efforts.

For now, you can see what we’ve gotten so far on documentation with 097:

http://docs.modxcms.com/ - PHP code documentation (slightly out of date)

http://docs.modxcms.com/modext/ - Standards and UI development tutorials in MODx097

http://svn.modxcms.com/trac/tattoo/ - The current 097 Trac bugtracker

http://svn.modxcms.com/crucible/browse/MODx - Fisheye, with detailed commit reports

And more to come...

Quote from: Maaike at Feb 07, 2008, 12:40 PM

I personally believe the best marketing tool for MODx would be better documentation.

Agreed and the code documentation is going to be stellar but the missing link is practical documentation, developer guides, examples, how tos and related links to articles, api docs and more. Who really enjoys reading code documentation? It can be full of jargon and elevated nomenclature that eventhough I don’t know the correct terms for much of what I do I can still write small apps in PHP.

Quote from: splittingred at Feb 07, 2008, 12:46 PM

For now, you can see what we’ve gotten so far on documentation with 097:

I am not going to complain but take action and work on some docs on my own but the code documentation is even a bit esoteric for day to day developers.

I like reading practical "guides" that help me do things not tell me all about all the parts and say here’s the guts now go build. People gain from little wins at building an app. This is one of the reasons so many people get frustrated at the beginning with MODx it is that they don’t get as many of those little wins initially. Guiding people into those little wins is key to having them dig deeper into "well now how can I do this?"

The best books I have read on programming, web design and marketing for that matter carry the reader through to success with demonstration and results. Step-by-steps, screencasts, and examples are what works. I get the impression that the Wiki is scary for some people to add to like they will break it if it isn’t 100% perfect or that they are not expert enough but a Wiki is not documentation it is a sharing tool.

Okay, I’ve come off the rails here.

I’m done like dinner on this thread.

Cheers,

Jay

When I got the MacHeist bundle a couple of weeks ago, it includes the SnapZ Pro video capture program. I’m gradually learning how to use it (it’s pretty easy, actually) and will be creating a whole bunch of video tutorials, starting with an installation tutorial.

I’m with Susan. I think video walk-throughs will be the best. And the best documentation I’ve seen is Codeigniters- video tutorials, wiki, and their official docs are great.

Quote from: smashingred at Feb 07, 2008, 02:37 PM

I like reading practical "guides" that help me do things not tell me all about all the parts and say here’s the guts now go build. People gain from little wins at building an app. This is one of the reasons so many people get frustrated at the beginning with MODx it is that they don’t get as many of those little wins initially. Guiding people into those little wins is key to having them dig deeper into "well now how can I do this?"

Exactly, that’s what I meant. There already are lots of helpful hints, tutorials etc, but they’re scattered all over the place right now (site, wiki, forums, help files within zip files etc), which makes it harder for people to find what they need. I think screencasts would be great, but I also believe the official documentation on the website needs to be updated and added to.

(BTW I know I’m not really in a position to say these things because I’m not helping out myself right now! )

Quote from: sottwell at Feb 07, 2008, 03:08 PM

When I got the MacHeist bundle a couple of weeks ago, it includes the SnapZ Pro video capture program. I’m gradually learning how to use it (it’s pretty easy, actually) and will be creating a whole bunch of video tutorials, starting with an installation tutorial.

I have been using SnapzProX for a year now, and it’s great for capturing stills and video (though iShowU seems a bit nicer for this).

But I agree it will be faster to create tutorials this way, and could vastly improve the learning curve...

Now we just need to get started, like Mark did for Ditto !

Mark used iShowU.

Does SnapZPro have the cool zooming that Camtisa (?) Studio can do?

David I am looking forward to all the screencasts coming. (I’ll build a couple simple ones maybe.)

On a related note about Ditto’s documentation while quite exhaustive (and exellent--thanks Mark) it is a bit overwhelming and disjointed from the MODx documentation (not Mark’s fault).

In an ideal world, documentation for all the snippets, modules and plugins that ship with MODx should be in the same format with a unified design, formatting, image sizes and references to MODx syntax for templates and such.

I too look forward to the screencasts.

Quote from: smashingred at Feb 07, 2008, 05:31 PM

On a related note about Ditto’s documentation while quite exhaustive (and exellent--thanks Mark) it is a bit overwhelming and disjointed from the MODx documentation (not Mark’s fault).

In an ideal world, documentation for all the snippets, modules and plugins that ship with MODx should be in the same format with a unified design, formatting, image sizes and references to MODx syntax for templates and such.

I do understand the desire for some improvement in the quality and quantity of the core documentation, but as far as add-ons go, this is where I have to disagree (though my opinion is mostly a result of my vision to completely isolate add-ons from MODx itself, i.e. will not be shipped with the future core). In general, I don’t want to discourage creativity or adoption by add-on developers, by imposing unnecessary "standards" at a critical point in the growth of MODx. That said, I do believe useful tools and standards for all kinds of documentation will emerge as the developer community gains momentum, and as we make it through several upcoming transitions.

Not an ideal world; a practical one for the moment.

Quote from: ProWebscape at Feb 07, 2008, 03:19 PM

I’m with Susan. I think video walk-throughs will be the best. And the best documentation I’ve seen is Codeigniters- video tutorials, wiki, and their official docs are great.

Maybe it’s just me, but I hate video documentation. I’d much rather have something that allows me to go back to specific parts for reference. Replaying a video to catch something you missed just makes me tired.

The Red-Bean Subversion book is a perfect example of what I’d like to see. If there were a TortoiseSVN video, I don’t think I’d ever watch it.

Bob