Add-On Documentation and Tutorials Discussions

Quote from: matthew at Jan 28, 2007, 12:36 PM

That worked but didn’t get that from the documentation... I think the vast amount of features it has makes the documentation to hard to understand if all one wants is something simple.

This sounds like a great opportunity for you to give back by helping withe the documentation or writing a tutorial on the wiki.

I have to admit - he’s got a point. MODx is nice, robust, and badass. But the documentation leaves a lot to be desired. Sometimes when you ask how to do something on this board, someone snaps back, "Why don’t you read the documentation?" and you think, "I did...it listed a bunch of parameters, but didn’t mention a thing about ’first step’, ’second step’, etc."

Tutorials are whats needed for most of these additions, to really understand them.

I’m looking to use WayFinder, but am not sure how i’d go about it. I’ve got subordinate pages that I want to automatically create a menu, but how would I even start? I have no clue.

The MODx documentation will likely lag for the immediate future because many things are in transition. Right now an ideal target for MODx is pretty well outlined in my signature, but we’re open to everyone. We’re not trying to be a plug-and-play solution and for some folks MODx just won’t make any sense. It’s unfortunate, but it’s the truth. We have to pick our battles with the limited resources we’ve got, and we’ve chosen to rectify a lot of things at the core level that are not quite optimal instead of spending a lot of time on documenting what’s going to change within a short timeframe of completing the documentation, which in turn will require a new documentation effort. (And would result in an even longer delay to proper and relevant documentation in the first place.)

Anyone that wants to step up to the plate and take a stab at it though is more than welcome to do so.

Quote from: QManning at Jan 28, 2007, 10:28 PM

I have to admit - he’s got a point. ...
Tutorials are whats needed for most of these additions, to really understand them.

Yes, but writing a tutorial is more challenging than mere documentation. Because it requires a "newbie-experience" (or a very good imagination), and while hassling around with all that stuff, you have to write a protocol of it, and then you have to try to filter out your personal preferences to adjust it to an audience you do not know much about.
Basically I think that writing tutorials can be more difficult and time-consuming than producing new code - honestly!
And this is a fact that does not only apply to MODx: more code and options than ways to find your way through.
So, the name "wayfinder" for this quite complex "modx-subsystem" sounds almost ironical.

Quote from: rthrash at Jan 28, 2007, 10:33 PM

which in turn will require a new documentation effort. (And would result in an even longer delay to proper and relevant documentation in the first place.)
Anyone that wants to step up to the plate and take a stab at it though is more than welcome to do so.

Yes, but that makes it even worse - in the first place. I would suggest a model of "developer-firstuser" pairs, where the developer is responsible to create good code and let the "firstuser" make experiences with it. (The "firstuser" could be almost anyone!) Then this communication has to find a way of keeping the record to create a basis for "real life" tutorials.

Having to work alone is, as I see it, an obstacle for contributions from outside the "core team".
I’m willing and (hopefully) able to take the "firstuser’s part" in one or two of those "sub-teams" in charge for understandable introduction and documentation, be it for aspects of the core-code or for plugins, snippets etc.

Thanks silent! What’s the first step to getting started?

Building pairs!
So, for instance, I’m quite eager to learn more about the subject of this thread, "wayfinder".
(I’m still stuck with "dropmenu" - what a shame!)
So, the original developer of wayfinder may contact me to build a "user’s experience team".
And then we could figure out the ways of communicating and keeping the record.

The same, obviously, applies to changes in the core, but in cases like this, access and use of "subverted" pre-release versions of MODx is required from the "firstuser’s" part.

I guess, being built upon such a "pair" could be beneficial for the audience as well as for the participiants - and, last not least, for MODx!

[EDIT] One way of communicating within those pairs might be using a simple forum. This can enable others to have a look or even comment on specific aspects. And it could "monitor" the original pair to prevent "insider" effects. And, helas, the thread in this forum would be the tutorial in a rough, early version, which in most cases, would become the final tutorial by post-editing! The main difference to the current support-threads here would be that it is committed to a FIRST user, tutorial-like approach, where the role of the "first user" is clearly defined. Other than the current threads they would "tell a story" of a specific, individual experience, which should make it a lot easier to relate it to your own first use-case.[/EDIT]

hey!! excuse me for my english i’m french.
I just would like to know if you had contact with the creator of WayFinder. You told about a "user’s experience team". I try to build my menu with WayFinder and I meet some difficulties. So if you can help me...thanks a lot

Quote from: djo-x at Jun 13, 2007, 01:21 PM

hey!! excuse me for my english i’m french.
I just would like to know if you had contact with the creator of WayFinder. You told about a "user’s experience team". I try to build my menu with WayFinder and I meet some difficulties. So if you can help me...thanks a lot

Just open up a topic in the wayfinder category: http://modxcms.com/forums/index.php/board,182.0.html

ok thanks but my matter is that I don’t success to understand the link between the snippet call and the chunk used. Where i have to write the chunk?
i find that the muddydogpaws site is great but i miss one information to continue.