On Mon, Feb 8, 2010 at 8:22 AM, neweller <[email protected]> wrote:
> "we have frequently found ourselves venting over > the seeming lack of documentation" > I've said it before, but I'll say it again: PLEASE let us know SPECIFICALLY what you want to see that you think is lacking in the way of documentation. I hear from people all the time that Mach-II has great documentation, while others find things missing, so "lack of documentation" comments in the abstract simply aren't helpful. File a ticket, or email the list with "I was doing X but couldn't find documentation" information, but please don't just make the generic statement that there's a lack of documentation because A) it isn't helpful, and B) it isn't true. We have copious amounts of documentation on a lot of aspects of Mach-II. Are there specific areas where it could be improved? Sure there are. But our users need to let us know what those areas are. It's not at all uncommon for people to ask about how to do something on the mailing list and our response is to point them to a link on the wiki that outlines in great detail specifically what they want to do, so make sure and search the wiki before assuming there's no documentation on what you're trying to do. As Kurt said we're a very small team of folks all of whom have full-time day jobs and lives outside of work, and we're doing all this work gratis, so if people have the time, knowledge, and inclination, documentation is the #1 way you can help the project. I just checked the tickets for documentation requests, and every single one in there was submitted by Team Mach-II (by Peter to be exact). Not one was submitted by any of our users. If you search the wiki and don't find what you're looking for, submit a documentation request ticket, and be as specific as possible. This helps us help you. If no one tells us specifically what they need we can't possibly know what's lacking from your perspective. > > As of 1.8 Simplicity RC2 I wanted to upgrade and take use of the new > features such as HTML Helper to condense the site into one main app > but this has been very frustrating. Basically I have resorted to > reverse engineering the Dashboard 1.1.0 just to see some of these new > features in use. > What features specifically? There's a pretty extensive wiki page on the HTML helper property: http://greatbiztoolsllc.trac.cvsdude.com/mach-ii/wiki/HTMLHelperProperty Now if there are specific aspects of how to use it that you see lacking, please file a ticket, or if you work through some things that aren't documented that you think should be, please add the information to the wiki. ANYONE can edit the wiki so please don't feel like we don't want people to dive in and contribute. Again, that's the #1 way you can help the project. > > Just as a side note it appears 1.8 has been left for dead and all > attention has been moved to 1.9. Why on earth would you say 1.8 has been left for dead? Peter was in Italy for a while so we'll get the gold release out this week. If you have concerns or questions please ask before assuming something's been left for dead. Yes, we started on 1.9 (and 2.0 for that matter) already so we can get to milestone releases on those versions more quickly, and there's no reason not to do so once 1.8 has reached RC stage, particularly due to the milestone release cycle we're moving to with 1.9. I get the impression that a lot of these sorts of comments stem from a lack of understanding of how open source projects work. We don't wait until a version has its final release before moving ahead on features for new releases. > I think 1.8 is actually gold just not > released? This week. > I would like to commit to a version and get to learning of > HTML Helper but should I forget 1.8 and go straight to 1.9? > I know I'm on a bit of a rant here, but I do get extremely weary of the ridiculously strict adherence a lot of CFML developers have to "gold releases." I've been using 1.8 in production for months, as has Peter, as have numerous others. If you're worried about the state of the framework as relates to your applications, that means you don't have good testing in place. Waiting for the gold release of Mach-II isn't going to fix that problem for you. In my apps I test things and if they work, they work. I can start taking advantage of new Mach-II features right away. Again this goes back to a general lack of understanding of and general comfort level with open source projects. I run on nightly builds of Mach-II and even Open BlueDragon regularly and because I test things, I don't really care what label the developers slap on the projects I use. If you have good testing in place then any fear of whether or not things work is wholly unfounded. The CFML community as a whole needs to get away from that mindset in my opinion. Using new releases of Mach-II early in their development cycle is another huge way people can help the project. We test very thoroughly and even have a test suite in place, but we can't possibly think of everything. The sooner we can get people running real-world apps on new versions of Mach-II--even in testing--the sooner we can get any bugs worked out and get the final release out the door. If everyone waits until the "gold" stamp goes on a release then the project (and everyone using it) doesn't get the benefit of anything that might be uncovered in your applications. At a minimum I would hope people run betas or nightlies of Mach-II in test environments, because if you wait until the final release comes out you'll always be behind, particularly as we move to more rapid milestone releases in future versions of Mach-II. > > Once I get a better understanding of Mach-II I wouldn't mind helping > the Mach-II Wiki. I think a basic example of HTML Helper that changes > the layout / CSS / Javascript based on a user login would be a good > example to see on the Wiki. > > Thanks--finally we get to something specific. Again, check the wiki page link I provided above and if you don't see what you need there, file a ticket or edit the wiki yourself. And that goes for all documentation. As I mentioned above if after you search the wiki you still aren't finding the documentation you need, submit a ticket: http://greatbiztoolsllc.trac.cvsdude.com/mach-ii/newticket There's even a category for "documentation request." My apologies for the rant but everyone on the team works very hard, for free and completely in our spare time, to make what we feel is the best CFML framework available, and trust me when I say what we have planned for 1.9 and 2.0 will blow you away. Yes, there's room for improvement in a lot of areas of the project. There always will be. But please help us help you by filing tickets, which anyone can do, or contributing documentation directly to the wiki. I feel like people get frustrated when they don't find something they're looking for and instead of letting us know right away, they let the frustration build until they're downright angry about something missing that we didn't even know people needed. So in a nutshell, if you use Mach-II, PLEASE CONTRIBUTE BACK. Testing, writing documentation, or even simply submitting a ticket helps. Idle whining doesn't. -- Matthew Woodward [email protected] http://blog.mattwoodward.com identi.ca/Twitter: @mpwoodward Please do not send me proprietary file formats such as Word, PowerPoint, etc. as attachments. http://www.gnu.org/philosophy/no-word-attachments.html -- You received this message because you are subscribed to Mach-II for CFML list. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/mach-ii-for-coldfusion?hl=en SVN: http://greatbiztoolsllc.svn.cvsdude.com/mach-ii/ Wiki / Documentation / Tickets: http://greatbiztoolsllc.trac.cvsdude.com/mach-ii/
