Teaman wrote:
While I realize the "official" is less official due to the community aspect, I do assume that what is there is correct.
And it is. But again, there is no black and white, correct and not correct, etc. It depends on your situation and your skillset, which was one of the points I was trying to make in my previous email.
So I challenge you and the others more experienced that if something in there is misleading, then at a minimum, put some Notes or caveats in the docs wiki about there being simpler or alternative ways from what is described.
But again, it's not incorrect or even misleading. My interpretation of where you are on things is that you may be getting bogged down by taking on too much at once. If I'm wrong on that my apologies.
To leave erroneous or misleading information there is a disservice to those following in your footsteps trying to learn this stuff.
There's nothing erroneous or misleading about what's there. More on that below.
Comments of that nature take far less time than trying to rewrite sections complete with examples and illustrations and would help newbies like me realize it's not the "only way" to do something. Yes that goes without saying but when you are experienced, there are "better" or "easier" ways to do things.
Well, easier != better necessarily. And I'm not going out of my way to be difficult, but I also don't like oversimplifying things when they can't be. That's why I can't ever be a politician (among other reasons ;-).
Our goal is to provide people as much information as possible. Some things may click for some people, whereas other people need a bit different approach. So it isn't a matter of me going in and "correcting" anything Brian or Adrian wrote, because there's nothing wrong with it. It may not quite be gelling *for you* which is why I'm trying to figure out what might be helpful to you, because chances are there are other people in your exact same situation, or will be in the future, so adding that additional/different spin on things to the wiki will be helpful both for you and for people in the future who find themselves in your situation.
Your comments about newbies trying to bite off too much and overcomplicating... I don't recall seeing any docs that states "starting out just use this , this and this in the framework" later
Have you looked into all the other presentations and documentation available? I get the impression you're focusing on two articles on the wiki and because those two articles aren't quite working for you at this point, that you're suggesting I should add big disclaimers at the top of those particular documents warning newbies that these are "advanced" or something along those lines.
Perhaps that's taking the example a bit far, but the point in my mind is to make the information available in various forms and let people explore. Also, remember that this mailing list is a GREAT source of information as I hope you're finding out.
Again, I'm not trying to dismiss anything you're saying, but I also don't see that there's really anything "wrong" with the current documentation.
What may be helpful--and I'd like your feedback on this idea--is having a "beginner's roadmap" that might, along with some new documentation, be a better logical progression, or pointing people down a path, so that they might not dive into something about plugins when they don't even understand the basics of how Mach-II works.
Since I'm leaning on those of you more experienced, I simplly want some guidance on basics to use now and when to add in other framework aspects.
And that's what I hope you're getting from these discussions. From what you're saying I'm suggesting you:
A) watch the Head First Mach-II presentationB) focus on getting a handle on event announcements, the event object, and listener notifications
C) when B gets boring or as needs dictate, start exploring other areasThe other documentation you may be ignoring is (and this is based on your comment about subroutines that I snipped out) our "M2SFP" process. We document these in a very specific way: what problem does this feature solve, and how are we proposing to implement the solution. I'd think this could go a long way towards understanding some of the newer features, but the unfortunate thing is that these won't exist for features that have been in there since the beginning.
As always I'm happy to help further, and I'm starting to understand where you're coming from with these discussions and what we can do to improve our documentation, so I really appreciate you taking the time to tell us how we can improve.
-- Matt Woodward [email protected] http://www.mattwoodward.com/blogPlease do not send me proprietary file formats such as Word, PowerPoint, etc. as attachments.
http://www.gnu.org/philosophy/no-word-attachments.html
smime.p7s
Description: S/MIME Cryptographic Signature
