cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Derek Hohls" <DHo...@csir.co.za>
Subject How much is enough?
Date Sat, 25 Feb 2006 14:28:30 GMT
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
HelpDesk@csir.co.za.


This message has been scanned for viruses and dangerous content by MailScanner, 
and is believed to be clean.


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org


Mime
View raw message