This question has come up before, and will no doubt come up again - how much is "enough documentation" for a web application development platform? A recent Ellipse newsletter* asked this question and they argue that trust and confidence in its usage come from understanding: "the one benefit here that a lot of developers value, even if the framework isn't perfect, is that they feel confident in their ability to maintain the framework and fix bugs. They know exactly where the ResourceBundle loading is done, so there is no search necessary. They know to open up LeakyResourceBundleUtil.java and fix it, and because of this they feel confident; they can be accountable. What scares a lot of developers is using some well known framework and having the inevitable bug show up and then having no idea how to fix it. Mailing lists can help, but ultimately the bug could be in your huge mess of code which you can't share with anyone else to look at. Scary." I wonder if many people know and respect Cocoon as a stable and trusted framework; if yes, why, and if no, why not?? "How do you get them to feel confident enough in the platform that they can throw all their eggs into the basket and say "We are in this through thick and thin, I love you."? You provide documentation. In fact, you provide so much documentation that your documentation could kill a small horse. You document everything, not just Javadoc, but features, how-to's and styles of coding. You try to provide so much documentation that someone could search for "Splash screen", and not just find the Javadoc on Windows, but actually find a document on how to write a splash screen using your framework."
"When you make things accessible to developers, don't waste their time. Grease the wheels and give them the controls, they will love you for it. Is this too little too late for everyone else? God no. Keep it up I say, mush mush! The more documentation out there the more everyone is going to strive to improve and reuse these frameworks. At the end of the day, all we as developers want is something that we can trust our next app on." Food for thought here... Derek *EclipseZone Weekly Newletter, dated 2006-02-24 -- This message is subject to the CSIR's copyright, terms and conditions and e-mail legal notice. Views expressed herein do not necessarily represent the views of the CSIR. CSIR E-mail Legal Notice http://mail.csir.co.za/CSIR_eMail_Legal_Notice.html CSIR Copyright, Terms and Conditions http://mail.csir.co.za/CSIR_Copyright.html For electronic copies of the CSIR Copyright, Terms and Conditions and the CSIR Legal Notice send a blank message with REQUEST LEGAL in the subject line to [EMAIL PROTECTED] This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
